Add edoc info and target

Makefile

@@ -17,7 +17,8 @@ SRC_MODULES = \
 	kruskal \
 	heap \
 	union_find \
-	demo
+	demo \
+	doc
 
 TARGETS = \
 	src_target
@@ -36,6 +37,9 @@ src_target: $(SRC_MODULES:%=$(EBIN)/%.beam)
 $(EBIN)/%.beam: %.erl
 	$(ERLC) $(ERLC_FLAGS) -o $(EBIN) $<
 
+edoc:
+	@(./makedoc.rb)
+
 dialyze: $(TARGETS)
 	dialyzer -n -Wunmatched_returns $(EBIN)/*.beam
 

doc/overview.edoc

@@ -0,0 +1,20 @@
+@author Aggelos Giantsios
+@copyright 2013 Aggelos Giantsios
+@title Welcome to erlang-algorithms!
+@doc The goal of this project is to implement some useful algorithms and data structures in Erlang so as to help anyone who may need them.
+
+== Currently Implemented Data Structures ==
+<ul>
+  <li><a href="graph.html">Directed, Undirected, Weighted, Unweighted Graphs</a></li>
+  <li><a href="heap.html">Min / Max Heaps</a></li>
+  <li>Union / Find</li>
+</ul>
+
+== Currently Implemented Algorithms ==
+<ul>
+  <li>BFS</li>
+  <li>DFS</li>
+  <li>Dijkstra</li>
+  <li>Kruskal</li>
+</ul>
+

makedoc.rb

@@ -0,0 +1,5 @@
+#! /usr/bin/env ruby
+
+puts `erl -noinput -pa ebin/ -eval "doc:make_doc()" -s init stop`
+
+

src/doc.erl

@@ -0,0 +1,9 @@
+-module(doc).
+
+-compile(export_all).
+
+-spec make_doc() -> 'ok'.
+make_doc() ->
+  Mods = ["graph.erl", "heap.erl"],
+  Fs = lists:map(fun(M) -> filename:absname("src/" ++ M) end, Mods),
+  edoc:files(Fs, [{dir, "doc"}]).

src/graph.erl

@@ -1,43 +1,80 @@
 %%
+%% %CopyrightBegin%
+%%
 %% Copyright © 2013 Aggelos Giantsios
 %%
-
 %% Permission is hereby granted, free of charge, to any person obtaining a copy of this software 
 %% and associated documentation files (the “Software”), to deal in the Software without restriction, 
 %% including without limitation the rights to use, copy, modify, merge, publish, distribute, 
 %% sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is 
 %% furnished to do so, subject to the following conditions:
-
+%%
 %% The above copyright notice and this permission notice shall be included 
 %% in all copies or substantial portions of the Software.
-
+%%
 %% THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 
 %% TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 %% IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
 %% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
 %% CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
 %%
-%% Directed / Undirected Graphs
+%% %CopyrightEnd%
 %%
 
-%% This module implements directed and undirected graphs that are either weighted or unweighted.
-%% It is basically syntactic sugar for the digraph module with added support for undirected graphs.
+%% @copyright 2013 Aggelos Giantsios
+%% @author Aggelos Giantsios
+
+%% ============================================================================
+%% @doc Directed / Undirected Graphs
+%%
+%% <p>This module implements directed and undirected graphs that are either 
+%% weighted or unweighted.</p>
+%%
+%% <p>It is basically syntactic sugar for the digraph module with added 
+%% support for undirected graphs.</p>
+%%
+%% <h3>How to use</h3>
+%% <p>In order to create a graph you must load it from a file.
+%% The file that contains the graph must have the following format.</p>
+%% 
+%% <ul>
+%%   <li>The 1st line will consist of four terms separeted by a white space.
+%%     <ul>
+%%       <li>1st Term: Positive Integer N that denotes the number of vertices</li>
+%%       <li>2nd Term: Positive Integer M that denotes the number of edges.</li>
+%%       <li>3rd Term: Atom <code>directed</code> or <code>undirected</code> that denotes the type of the graph.</li>
+%%       <li>4th Term: Atom <code>unweighted</code> or <code>d</code> or <code>f</code> that denotes the type of the edge weights.
+%%         <ul>
+%%           <li><code>unweighted</code> is for an unweighted graph.</li>
+%%           <li><code>d</code> is for decimal integer weights.</li>
+%%           <li><code>f</code> is for floating point number weights in proper Erlang syntax.</li>
+%%         </ul>
+%%       </li>
+%%     </ul>
+%%   </li>
+%%   <li>The next M lines will consist of the edge descriptions. 
+%%       Each line will contain three terms : U V W. 
+%%       This will denote an edge from U to V with W weight.</li>
+%% </ul>
+%% 
+%% <p>For examples you can check the files in the test_data directory.</p>
+%% 
 
 -module(graph).
 
-%% External Exports
 -export([new_graph/1, del_graph/1, vertices/1, edges/1, edge_weight/2,
          edges_with_weights/1, out_neighbours/2, num_of_vertices/1,
          num_of_edges/1, pprint/1]).
 
-%% Exported Types
 -export_type([graph/0, vertex/0, edge/0]).
 
-%% Types Declarations
+%%
+%% @type graph(). A directed or undirected graph.
+%% <p>It is wrapper for a digraph with the extra information on its type.</p>
+%%
 -record(graph, {type :: graphtype(), graph :: digraph()}).
--type graph()  :: #graph{}.
--type vertex() :: non_neg_integer() | atom().
+-opaque graph()  :: #graph{}.
+-type vertex() :: non_neg_integer().
 -type edge()   :: {vertex(), vertex()}.
 -type graphtype()  :: 'directed' | 'undirected'.
 -type weighttype() :: 'unweighted' | 'd' | 'f'.
@@ -46,7 +83,7 @@
 %% Exported Functions
 %% ==========================================================
 
-%% Create a new graph from a file
+%% @doc Create a new graph from a file
 -spec new_graph(file:name()) -> graph().
 
 new_graph(File) ->
@@ -62,26 +99,26 @@ new_graph(File) ->
   'ok' = init_edges(G, M, IO, T, W),
   #graph{type=T, graph=G}.
 
-%% Delete a graph
+%% @doc Delete a graph
 -spec del_graph(graph()) -> 'true'.
 
 del_graph(G) ->
   digraph:delete(G#graph.graph).
 
-%% Get the vertices of a graph
+%% @doc Return a list of the vertices of a graph
 -spec vertices(graph()) -> [vertex()].
 
 vertices(G) ->
   digraph:vertices(G#graph.graph).
 
-%% Return the number of vertices in a graph
+%% @doc Return the number of vertices in a graph
 -spec num_of_vertices(graph()) -> non_neg_integer().
 
 num_of_vertices(G) ->
   Vs = vertices(G),
   length(Vs).
 
-%% Get the edges of a graph
+%% @doc Return a list of the edges of a graph
 -spec edges(graph()) -> [edge()].
 
 edges(G) ->
@@ -93,34 +130,34 @@ edges(G) ->
       remove_duplicate_edges(Es, [])
   end.
 
-%% Return the number of edges in a graph
+%% @doc Return the number of edges in a graph
 -spec num_of_edges(graph()) -> non_neg_integer().
 
 num_of_edges(G) ->
   Es = edges(G),
   length(Es).
 
-%% Get the weight of an edge
+%% @doc Return the weight of an edge
 -spec edge_weight(graph(), edge()) -> term().
 
 edge_weight(G, E) ->
   {E, _V1, _V2, W} = digraph:edge(G#graph.graph, E),
   W.
 
-%% Get the edges of a graph along with their weights
+%% @doc Return a list of the edges of a graph along with their weights
 -spec edges_with_weights(graph()) -> [{edge(), term()}].
 
 edges_with_weights(G) ->
   Es = edges(G),
   lists:map(fun(E) -> {E, edge_weight(G, E)} end, Es).
 
-%% Get the out neighbours of a vertex
+%% @doc Return a list of the out neighbours of a vertex
 -spec out_neighbours(graph(), vertex()) -> [vertex()].
 
 out_neighbours(G, V) ->
   digraph:out_neighbours(G#graph.graph, V).
 
-%% Pretty print a graph
+%% @doc Pretty print a graph
 -spec pprint(graph()) -> 'ok'.
 
 pprint(G) ->