6. Writing documentation for Erlang/OTP Releases¶
6.1. Learning erl_docgen¶
Writing documentation for Erlang/OTP requires adherence to the standard and format of the Erlang/OTP manual. To prepare the document, you need to use the tool called erl_docgen.
Erl_docgen uses the own XML tags and notation for writing the manual. The XML definition for writing a documentation of a module or an application is listed as the Reference Manual DTDs. I am not going into the details of the XML tag definitions, because they are given in the erl_docgen documentation, and rather can be easily understood by reading actual XML documentation.
6.2. Example of rand module documentation¶
For prototyping rand module, I set up a locally executable
documentation build environment. See the xml-doc directory of the
prototype repository for the further
details. You can also try doing full building of the documentation.
The following list is an example source XML file for Erlang/OTP rand
module, as provided in the prototype repository. The
rendered result can be accessed as an html file.
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>2015</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>rand</title>
<prepared></prepared>
<responsible></responsible>
<docno>1</docno>
<approved></approved>
<checked></checked>
<date></date>
<rev>A</rev>
<file>rand.xml</file>
</header>
<module>rand</module>
<modulesummary>Pseudo random number generation.</modulesummary>
<description>
<p>This module provides a random number generator. The module contains
a number of algorithms. The uniform distribution algorithms use the
<url href="http://xorshift.di.unimi.it">scrambled Xorshift algorithms by
Sebastiano Vigna</url>. The normal distribution algorithm uses the
<url href="http://www.jstatsoft.org/v05/i08">Ziggurat Method by Marsaglia
and Tsang</url>.</p>
<p>For some algorithms, jump functions are provided for generating
non-overlapping sequences for parallel computations.
The jump functions perform calculations
equivalent to perform a large number of repeated calls
for calculating new states. </p>
<p>The following algorithms are provided:</p>
<taglist>
<tag><c>exsplus</c></tag>
<item>
<p>Xorshift116+, 58 bits precision and period of 2^116-1</p>
<p>Jump function: equivalent to 2^64 calls</p>
</item>
<tag><c>exs64</c></tag>
<item>
<p>Xorshift64*, 64 bits precision and a period of 2^64-1</p>
<p>Jump function: not available</p>
</item>
<tag><c>exs1024</c></tag>
<item>
<p>Xorshift1024*, 64 bits precision and a period of 2^1024-1</p>
<p>Jump function: equivalent to 2^512 calls</p>
</item>
</taglist>
<p>The default algorithm is <c>exsplus</c>. If a specific algorithm is
required, ensure to always use <seealso marker="#seed-1">
<c>seed/1</c></seealso> to initialize the state.</p>
<p>Every time a random number is requested, a state is used to
calculate it and a new state is produced. The state can either be
implicit or be an explicit argument and return value.</p>
<p>The functions with implicit state use the process dictionary
variable <c>rand_seed</c> to remember the current state.</p>
<p>If a process calls
<seealso marker="#uniform-0"><c>uniform/0</c></seealso> or
<seealso marker="#uniform-1"><c>uniform/1</c></seealso> without
setting a seed first, <seealso marker="#seed-1"><c>seed/1</c></seealso>
is called automatically with the default algorithm and creates a
non-constant seed.</p>
<p>The functions with explicit state never use the process dictionary.</p>
<p><em>Examples:</em></p>
<p>Simple use; creates and seeds the default algorithm
with a non-constant seed if not already done:</p>
<pre>
R0 = rand:uniform(),
R1 = rand:uniform(),</pre>
<p>Use a specified algorithm:</p>
<pre>
_ = rand:seed(exs1024),
R2 = rand:uniform(),</pre>
<p>Use a specified algorithm with a constant seed:</p>
<pre>
_ = rand:seed(exs1024, {123, 123534, 345345}),
R3 = rand:uniform(),</pre>
<p>Use the functional API with a non-constant seed:</p>
<pre>
S0 = rand:seed_s(exsplus),
{R4, S1} = rand:uniform_s(S0),</pre>
<p>Create a standard normal deviate:</p>
<pre>
{SND0, S2} = rand:normal_s(S1),</pre>
<note>
<p>This random number generator is not cryptographically
strong. If a strong cryptographic random number generator is
needed, use one of functions in the
<seealso marker="crypto:crypto"><c>crypto</c></seealso>
module, for example, <seealso marker="crypto:crypto">
<c>crypto:strong_rand_bytes/1</c></seealso>.</p>
</note>
</description>
<datatypes>
<datatype>
<name name="alg"/>
</datatype>
<datatype>
<name name="state"/>
<desc><p>Algorithm-dependent state.</p></desc>
</datatype>
<datatype>
<name name="export_state"/>
<desc><p>Algorithm-dependent state that can be printed or saved to
file.</p></desc>
</datatype>
</datatypes>
<funcs>
<func>
<name name="export_seed" arity="0"/>
<fsummary>Export the random number generation state.</fsummary>
<desc><marker id="export_seed-0"/>
<p>Returns the random number state in an external format.
To be used with <seealso marker="#seed-1"><c>seed/1</c></seealso>.</p>
</desc>
</func>
<func>
<name name="export_seed_s" arity="1"/>
<fsummary>Export the random number generation state.</fsummary>
<desc><marker id="export_seed_s-1"/>
<p>Returns the random number generator state in an external format.
To be used with <seealso marker="#seed-1"><c>seed/1</c></seealso>.</p>
</desc>
</func>
<func>
<name name="jump" arity="0"/>
<fsummary>Return the seed after performing jump calculation
to the state in the process dictionary.</fsummary>
<desc><marker id="jump-0" />
<p>Returns the state
after performing jump calculation
to the state in the process dictionary.</p>
<p>This function generates a <c>not_implemented</c> error exception
when the jump function is not implemented for
the algorithm specified in the state
in the process dictionary.</p>
</desc>
</func>
<func>
<name name="jump" arity="1"/>
<fsummary>Return the seed after performing jump calculation.</fsummary>
<desc><marker id="jump-1" />
<p>Returns the state after performing jump calculation
to the given state. </p>
<p>This function generates a <c>not_implemented</c> error exception
when the jump function is not implemented for
the algorithm specified in the state.</p>
</desc>
</func>
<func>
<name name="normal" arity="0"/>
<fsummary>Return a standard normal distributed random float.</fsummary>
<desc>
<p>Returns a standard normal deviate float (that is, the mean
is 0 and the standard deviation is 1) and updates the state in
the process dictionary.</p>
</desc>
</func>
<func>
<name name="normal_s" arity="1"/>
<fsummary>Return a standard normal distributed random float.</fsummary>
<desc>
<p>Returns, for a specified state, a standard normal
deviate float (that is, the mean is 0 and the standard
deviation is 1) and a new state.</p>
</desc>
</func>
<func>
<name name="seed" arity="1"/>
<fsummary>Seed random number generator.</fsummary>
<desc>
<marker id="seed-1"/>
<p>Seeds random number generation with the specifed algorithm and
time-dependent data if <anno>AlgOrExpState</anno> is an algorithm.</p>
<p>Otherwise recreates the exported seed in the process dictionary,
and returns the state. See also
<seealso marker="#export_seed-0"><c>export_seed/0</c></seealso>.</p>
</desc>
</func>
<func>
<name name="seed" arity="2"/>
<fsummary>Seed the random number generation.</fsummary>
<desc>
<p>Seeds random number generation with the specified algorithm and
integers in the process dictionary and returns the state.</p>
</desc>
</func>
<func>
<name name="seed_s" arity="1"/>
<fsummary>Seed random number generator.</fsummary>
<desc>
<p>Seeds random number generation with the specifed algorithm and
time-dependent data if <anno>AlgOrExpState</anno> is an algorithm.</p>
<p>Otherwise recreates the exported seed and returns the state.
See also <seealso marker="#export_seed-0">
<c>export_seed/0</c></seealso>.</p>
</desc>
</func>
<func>
<name name="seed_s" arity="2"/>
<fsummary>Seed the random number generation.</fsummary>
<desc>
<p>Seeds random number generation with the specified algorithm and
integers and returns the state.</p>
</desc>
</func>
<func>
<name name="uniform" arity="0"/>
<fsummary>Return a random float.</fsummary>
<desc><marker id="uniform-0"/>
<p>Returns a random float uniformly distributed in the value
range <c>0.0 < <anno>X</anno> < 1.0</c> and
updates the state in the process dictionary.</p>
</desc>
</func>
<func>
<name name="uniform" arity="1"/>
<fsummary>Return a random integer.</fsummary>
<desc><marker id="uniform-1"/>
<p>Returns, for a specified integer <c><anno>N</anno> >= 1</c>,
a random integer uniformly distributed in the value range
<c>1 <= <anno>X</anno> <= <anno>N</anno></c> and
updates the state in the process dictionary.</p>
</desc>
</func>
<func>
<name name="uniform_s" arity="1"/>
<fsummary>Return a random float.</fsummary>
<desc>
<p>Returns, for a specified state, random float
uniformly distributed in the value range <c>0.0 <
<anno>X</anno> < 1.0</c> and a new state.</p>
</desc>
</func>
<func>
<name name="uniform_s" arity="2"/>
<fsummary>Return a random integer.</fsummary>
<desc>
<p>Returns, for a specified integer <c><anno>N</anno> >= 1</c>
and a state, a random integer uniformly distributed in the value
range <c>1 <= <anno>X</anno> <= <anno>N</anno></c> and a
new state.</p>
</desc>
</func>
</funcs>
</erlref>