Merge pull request #32 from uwiger/uw-add_ex_doc

Uw add ex doc
uwiger · Oct 7, 2023 · ecc17d2 · ecc17d2
2 parents 4a0a843 + 04bcb6c
commit ecc17d2
Show file tree

Hide file tree

Showing 10 changed files with 33 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 # Edown - Markdown generated from Edoc #
 
-Copyright (c) 2014 Ulf Wiger
+Copyright (c) 2014-23 Ulf Wiger
 
 __Authors:__ [`ulf@wiger.net`](mailto:ulf@wiger.net).
 

diff --git a/doc/README.md b/doc/README.md
@@ -2,7 +2,7 @@
 
 # Edown - Markdown generated from Edoc #
 
-Copyright (c) 2014 Ulf Wiger
+Copyright (c) 2014-23 Ulf Wiger
 
 __Authors:__ [`ulf@wiger.net`](mailto:ulf@wiger.net).
 

diff --git a/doc/edown_doclet.md b/doc/edown_doclet.md
@@ -28,9 +28,10 @@ __Authors:__ Ulf Wiger ([`ulf@wiger.net`](mailto:ulf@wiger.net)).
 ### run/2 ###
 
 <pre><code>
-run(Command::<a href="#type-doclet_gen">doclet_gen()</a> | <a href="#type-doclet_toc">doclet_toc()</a>, Ctxt::<a href="#type-edoc_context">edoc_context()</a>) -&gt; ok
+run(Command, Ctxt) -&gt; ok
 </code></pre>
-<br />
+
+<ul class="definitions"><li><code>Command = <a href="https://www.erlang.org/doc/man/edoc_doclet.html#type-command">edoc_doclet:command()</a></code></li><li><code>Ctxt = <a href="https://www.erlang.org/doc/man/edoc_doclet.html#type-context">edoc_doclet:context()</a></code></li></ul>
 
 Main doclet entry point.
 

diff --git a/doc/edown_layout.md b/doc/edown_layout.md
@@ -107,14 +107,14 @@ the source file. The default value is <code>true</code>.
 
 
 
-<dd>Specifies an <a docgen-rel="seeapp" docgen-href="xmerl:index" href="https://www.erlang.org/doc/man/index.html" target="_top"><code>xmerl</code></a> callback module to be
+<dd>Specifies an <code>xmerl</code> callback module to be
 used for exporting the documentation. See <a docgen-rel="seemfa" docgen-href="xmerl:xmerl#export_simple_content/2" href="https://www.erlang.org/doc/man/xmerl.html#export_simple_content-2"><code>//xmerl/xmerl:export_simple_content/2</code></a> for details.
 </dd>
 
 
 
 
-__See also:__ [//edoc/edoc:layout/2](https://www.erlang.org/doc/man/edoc.html#layout-2), [edown_doclet:layout/2](edown_doclet.md#layout-2).
+__See also:__ [//edoc/edoc:layout/2](https://www.erlang.org/doc/man/edoc.html#layout-2).
 
 <a name="overview-2"></a>
 

diff --git a/doc/edown_make.md b/doc/edown_make.md
@@ -21,9 +21,10 @@
 ### from_script/1 ###
 
 <pre><code>
-from_script(Config::ConfigFile) -&gt; ok | {error, Reason}
+from_script(ConfigFile) -&gt; ok | {error, Reason}
 </code></pre>
-<br />
+
+<ul class="definitions"><li><code>ConfigFile = <a href="https://www.erlang.org/doc/man/file.html#type-filename">file:filename()</a></code></li><li><code>Reason = any()</code></li></ul>
 
 Reads ConfigFile and calls [`edoc:application/3`](edoc.md#application-3)
 
@@ -38,9 +39,10 @@ This function does not manage dependencies. It is simply a wrapper around
 ### main/1 ###
 
 <pre><code>
-main(Args::[Config]) -&gt; no_return()
+main(Args) -&gt; no_return()
 </code></pre>
-<br />
+
+<ul class="definitions"><li><code>Args = <a href="https://www.erlang.org/doc/man/proplists.html#type-proplist">proplists:proplist()</a></code></li></ul>
 
 Escript entry point for building edown (or edoc) documentation
 
@@ -54,10 +56,10 @@ that the edown BEAM files are in the Erlang path (e.g. using $ERL_LIBS).
 The `edown_make` escript also accepts `-pa P` and/or `-pz P` flags as a
 means of locating the edown byte code.
 
-Note, however, that the function `edoc_make:main/1` only expects the
+Note, however, that the function `edown_make:main/1` only expects the
 config file as an input argument, corresponding to
 
-`escript edoc_make.beam ConfigFile`
+`escript edown_make.beam ConfigFile`
 
 (The reason for this is that if the beam file can be passed directly to
 the escript command, setting the path should also be doable that way).

diff --git a/doc/overview.edoc b/doc/overview.edoc
@@ -1,5 +1,5 @@
 @author <ulf@wiger.net>
-@copyright 2014 Ulf Wiger
+@copyright 2014-23 Ulf Wiger
 
 @title Edown - Markdown generated from Edoc
 

diff --git a/rebar.config b/rebar.config
@@ -7,6 +7,12 @@
 
 {clean_files, ["*~","*/*~","ebin/*.beam"]}.
 
+{ex_doc, [
+     {extras, ["README.md"]},
+     {main, "README.md"},
+     {source_url, "https://github.com/uwiger/edown"}
+]}.
+
 %% This is a reasonable set of options to use for edown, but edown
 %% doesn't actually use rebar to make its own docs.
 %% {edoc_opts, [{doclet, edown_doclet},

diff --git a/src/edown_doclet.erl b/src/edown_doclet.erl
@@ -47,7 +47,6 @@
 %% usually include the data from the edoc-info file in the target
 %% directory, if it exists.)
 
-%% @spec (Command::doclet_gen() | doclet_toc(), edoc_context()) -> ok
 %% @doc Main doclet entry point.
 %%
 %% Also see {@link //edoc/edoc:layout/2} for layout-related options, and
@@ -100,7 +99,9 @@
 %% INHERIT-OPTIONS: overview/4
 %% INHERIT-OPTIONS: copy_stylesheet/2
 %% INHERIT-OPTIONS: stylesheet/1
-
+-spec run(Command, Ctxt) -> ok
+	      when Command :: edoc_doclet:command(),
+		   Ctxt :: edoc_doclet:context().
 run(#doclet_gen{}=Cmd, Ctxt) ->
     gen(Cmd#doclet_gen.sources,
 	Cmd#doclet_gen.app,

diff --git a/src/edown_layout.erl b/src/edown_layout.erl
@@ -77,13 +77,12 @@
 %%  </dd>
 %%  <dt>{@type {xml_export, Module::atom()@}}
 %%  </dt>
-%%  <dd>Specifies an {@link //xmerl. `xmerl'} callback module to be
+%%  <dd>Specifies an `xmerl' callback module to be
 %%      used for exporting the documentation. See {@link
 %%      //xmerl/xmerl:export_simple_content/2} for details.
 %%  </dd>
 %% </dl>
 %%
-%% @see edown_doclet:layout/2
 %% @see //edoc/edoc:layout/2
 
 %% NEW-OPTIONS: xml_export, index_columns, stylesheet

diff --git a/src/edown_make.erl b/src/edown_make.erl
@@ -4,7 +4,8 @@
 -export([from_script/1]).
 -export([main/1]).
 
-%% @spec main(Args::[Config]) -> no_return()
+-spec main(Args) -> no_return()
+	      when Args :: proplists:proplist().
 %% @doc Escript entry point for building edown (or edoc) documentation
 %%
 %% Usage: edown_make -config ConfigFile [-pa P] [-pz P]
@@ -17,10 +18,10 @@
 %% The `edown_make' escript also accepts `-pa P' and/or `-pz P' flags as a
 %% means of locating the edown byte code.
 %%
-%% Note, however, that the function `edoc_make:main/1' only expects the
+%% Note, however, that the function `edown_make:main/1' only expects the
 %% config file as an input argument, corresponding to
 %%
-%% `escript edoc_make.beam ConfigFile'
+%% `escript edown_make.beam ConfigFile'
 %%
 %% (The reason for this is that if the beam file can be passed directly to
 %% the escript command, setting the path should also be doable that way).
@@ -35,7 +36,9 @@ main([Config]) ->
 	    halt(1)
     end.
 
-%% @spec from_script(ConfigFile) -> ok | {error, Reason}
+-spec from_script(ConfigFile) -> ok | {error, Reason}
+	      when ConfigFile :: file:filename(),
+		   Reason :: any().
 %% @doc Reads ConfigFile and calls {@link edoc:application/3}
 %%
 %% The ConfigFile will be read using {@link file:script/1}, and should return