Documentation generation

- Add overview - Fix EDoc related warnings. - Add Makefile targets for generate public and private documentation. - Add .gitignore settings related to documentation generation. - Add badges
erlangpack · Jun 6, 2022 · d9be492 · d9be492
1 parent 4a66378
commit d9be492
Show file tree

Hide file tree

Showing 8 changed files with 119 additions and 69 deletions.
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,4 @@ deps
 src/mimetypes_scan.erl
 src/mimetypes_parse.erl
 rebar3
+doc/*
diff --git a/Makefile b/Makefile
@@ -21,8 +21,19 @@ dialyzer: $(REBAR)
 xref: $(REBAR)
 	$(REBAR) as test xref
 
-clean: $(REBAR)
+clean: $(REBAR) clean_doc
 	$(REBAR) clean
+
+clean_doc:
+	@rm -f doc/*.html
+	@rm -f doc/erlang.png
+	@rm -f doc/edoc-info	
+
+edoc: $(REBAR)
+	$(REBAR) edoc
+
+edoc_private:  $(REBAR)
+	$(REBAR) as edoc_private edoc
 
 ./rebar3:
 	$(ERL) -noshell -s inets -s ssl \

diff --git a/README.md b/README.md
@@ -1,9 +1,12 @@
+[![Build Status][gh badge]][gh]
+[![Hex.pm version][hexpm version]][hexpm]
+[![Hex.pm Downloads][hexpm downloads]][hexpm]
+[![Hex.pm Documentation][hexdocs documentation]][hexdocs]
+[![Erlang Versions][erlang version badge]][gh]
+
 mimetypes
 =========
 
-![Test](https://github.com/erlangpack/mimetypes/workflows/Test/badge.svg)
-[![Hex pm](http://img.shields.io/hexpm/v/mimetypes.svg?style=flat)](https://hex.pm/packages/mimetypes)
-
 `mimetypes` is an Erlang library to fetch MIME extension/name mappings.
 
 Usage
@@ -66,3 +69,13 @@ config file specified using the ```erl -config``` flag.
     ]}
 ]}].
 ```
+
+<!-- Badges -->
+[hexpm]: https://hex.pm/packages/mimetypes
+[hexpm version]: https://img.shields.io/hexpm/v/mimetypes.svg?style=flat-curcle "Hex version"
+[hexpm downloads]: https://img.shields.io/hexpm/dt/mimetypes.svg?style=flat-curcle
+[hexdocs documentation]: https://img.shields.io/badge/hex-docs-purple.svg?style=flat-curcle
+[hexdocs]: https://hexdocs.pm/mimetypes
+[gh]: https://github.com/erlangpack/mimetypes/actions/workflows/test.yaml
+[gh badge]: https://github.com/erlangpack/mimetypes/workflows/Test/badge.svg
+[erlang version badge]: https://img.shields.io/badge/Supported%20Erlang%2FOTP-21%20to%2023-blue.svg?style=flat-curcle
diff --git a/rebar.config b/rebar.config
@@ -31,6 +31,11 @@
           {warnings, [
               no_return
           ]}
-        ]}
+        ]},
+		{doc_private, [
+			{edoc_opts, [
+				{private, true}
+			]}
+		]}
     ]}
 ]}.
diff --git a/src/mimetypes.erl b/src/mimetypes.erl
@@ -198,31 +198,27 @@ checkdefault(undefined) -> [<<"application/octet-stream">>];
 checkdefault(Other=[_|_]) -> Other.
 
 
-%%--------------------------------------------------------------------
-%% @doc
-%% Starts the server
-%%
-%% @spec start_link() -> {ok, Pid} | ignore | {error, Error}
-%% @end
-%%--------------------------------------------------------------------
+%% @doc Starts the server
+
 start_link() ->
     gen_server:start_link({local, ?SERVER}, ?MODULE, [], []).
 
 %%%===================================================================
 %%% gen_server callbacks
 %%%===================================================================
 
-%%--------------------------------------------------------------------
 %% @private
-%% @doc
-%% Initializes the server
-%%
-%% @spec init(Args) -> {ok, State} |
-%%                     {ok, State, Timeout} |
-%%                     ignore |
-%%                     {stop, Reason}
-%% @end
-%%--------------------------------------------------------------------
+%% @doc Initializes the server
+
+-spec init(Args) -> Result when
+	Args :: list(),
+	Result :: {ok, State} | 
+                       {ok, State, Timeout} |
+                       ignore |
+                       {stop, Reason},
+	State :: term(),
+	Timeout :: timeout(),
+	Reason :: term().
 init([]) ->
     case code:which(?MAPMOD) of
         non_existing ->
@@ -249,20 +245,28 @@ init([]) ->
     ok = filter_modules(),
     {ok, #state{}}.
 
-%%--------------------------------------------------------------------
 %% @private
-%% @doc
-%% Handling call messages
-%%
-%% @spec handle_call(Request, From, State) ->
-%%                                   {reply, Reply, State} |
-%%                                   {reply, Reply, State, Timeout} |
-%%                                   {noreply, State} |
-%%                                   {noreply, State, Timeout} |
-%%                                   {stop, Reason, Reply, State} |
-%%                                   {stop, Reason, State}
-%% @end
-%%--------------------------------------------------------------------
+%% @doc Handling call messages
+
+-spec handle_call(Request, From, State) -> Result when
+	Request :: term(),
+	From :: gen_server:from(),
+	State :: term(),
+	Result :: {reply,Reply,NewState}
+				  | {reply,Reply,NewState,Timeout}
+				  | {reply,Reply,NewState,hibernate}
+				  | {reply,Reply,NewState,{continue,Continue}}
+				  | {noreply,NewState}
+				  | {noreply,NewState,Timeout}
+				  | {noreply,NewState,hibernate}
+				  | {noreply,NewState,{continue,Continue}}
+				  | {stop,Reason,Reply,NewState}
+				  | {stop,Reason,NewState},
+	Reply :: term(),
+	NewState :: term(),
+	Timeout :: timeout(),
+	Continue :: term(),
+	Reason :: term().
 handle_call({create, Name}, _From, State) ->
     Modules = ?DISPMOD:modules(),
     case lists:keyfind(Name, 1, Modules) of
@@ -296,54 +300,66 @@ handle_call({load, Name, New}, _From, #state{}=State) ->
 handle_call(_Msg, _From, State) ->
     {reply, ok, State}.
 
-%%--------------------------------------------------------------------
 %% @private
-%% @doc
-%% Handling cast messages
-%%
-%% @spec handle_cast(Msg, State) -> {noreply, State} |
-%%                                  {noreply, State, Timeout} |
-%%                                  {stop, Reason, State}
-%% @end
-%%--------------------------------------------------------------------
+%% @doc Handling cast messages
+
+-spec handle_cast(Request, State) -> Result when
+	Request :: term(),
+	State :: term(),
+	Result :: {noreply,NewState}
+			  | {noreply,NewState,Timeout}
+			  | {noreply,NewState,hibernate}
+			  | {noreply,NewState,{continue,Continue}}
+			  | {stop,Reason,NewState},
+	NewState :: term(),
+	Timeout :: timeout(),
+	Continue :: term(),
+	Reason :: term().
 handle_cast(_Msg, State) ->
     {noreply, State}.
 
-%%--------------------------------------------------------------------
 %% @private
-%% @doc
-%% Handling all non call/cast messages
-%%
-%% @spec handle_info(Info, State) -> {noreply, State} |
-%%                                   {noreply, State, Timeout} |
-%%                                   {stop, Reason, State}
-%% @end
-%%--------------------------------------------------------------------
+%% @doc Handling all non call/cast messages
+
+-spec handle_info(Info, State) -> Result when
+	Info :: timeout | term(),
+	State :: term(),
+	Result :: {noreply,NewState}
+			  | {noreply,NewState,Timeout}
+			  | {noreply,NewState,hibernate}
+			  | {noreply,NewState,{continue,Continue}}
+			  | {stop,Reason,NewState},
+	NewState :: term(),
+	Continue :: term(),
+	Timeout :: timeout(),
+	Reason :: normal | term().
 handle_info(_Info, State) ->
     {noreply, State}.
 
-%%--------------------------------------------------------------------
 %% @private
-%% @doc
-%% This function is called by a gen_server when it is about to
+%% @doc This function is called by a gen_server when it is about to
 %% terminate. It should be the opposite of Module:init/1 and do any
 %% necessary cleaning up. When it returns, the gen_server terminates
 %% with Reason. The return value is ignored.
-%%
-%% @spec terminate(Reason, State) -> void()
-%% @end
-%%--------------------------------------------------------------------
+
+-spec terminate(Reason, State) -> Result when
+	Reason :: normal | shutdown | {shutdown,term()} | term(),
+	State :: term(),
+	Result :: term().
 terminate(_Reason, _State) ->
     ok.
 
-%%--------------------------------------------------------------------
 %% @private
-%% @doc
-%% Convert process state when code is changed
-%%
-%% @spec code_change(OldVsn, State, Extra) -> {ok, NewState}
-%% @end
-%%--------------------------------------------------------------------
+%% @doc Convert process state when code is changed
+
+-spec code_change(OldVsn, State, Extra) -> Result when
+	OldVsn :: Vsn | {down, Vsn},
+	Vsn :: term(),
+	State :: term(),
+	Extra :: term(),
+	Result :: {ok, NewState} | {error, Reason},
+	NewState :: term(),
+	Reason :: term().
 code_change(_OldVsn, State, _Extra) ->
     {ok, State}.
 

diff --git a/src/mimetypes_app.erl b/src/mimetypes_app.erl
@@ -23,7 +23,8 @@
 % CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 % IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 % OF SUCH DAMAGE.
-
+%
+% @private
 -module(mimetypes_app).
 
 -behaviour(application).

diff --git a/src/mimetypes_loader.erl b/src/mimetypes_loader.erl
@@ -23,7 +23,8 @@
 % CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 % IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 % OF SUCH DAMAGE.
-
+%
+% @private
 -module(mimetypes_loader).
 
 -export([start_link/0]).

diff --git a/src/mimetypes_sup.erl b/src/mimetypes_sup.erl
@@ -23,6 +23,8 @@
 % CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 % IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 % OF SUCH DAMAGE.
+%
+% @private
 
 -module(mimetypes_sup).
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,3 +5,4 @@ deps @@
     src/mimetypes_scan.erl
     src/mimetypes_parse.erl
     rebar3
+    doc/*