.. _haredoc:

API documentation
=================

Documentation on modules installed on your system, including the standard
library and third-party modules, is available in your terminal via the
``haredoc`` command.

.. raw:: html

   <script async id="asciicast-LhQz0OJEhwnHljOuaxmcQ17Oc" src="https://asciinema.org/a/LhQz0OJEhwnHljOuaxmcQ17Oc.js"></script>

.. note::
   For full details on the usage of the haredoc command, see its manpage: ``man
   haredoc``.

Writing documentation
---------------------

To document a declaration in Hare (a function, type, constant, etc), simply
write a comment directly above the declaration, like so:

.. code-block:: hare

   // This is an example function.
   export fn example() void = {
           // ...
   };

Hare documentation uses a very simple markup format, with the following
features:

Referencing other Hare symbols
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To reference other Hare symbols, wrap them in two square brackets, like so:

.. code-block:: hare

   // This is an example function.
   //
   // See also [[os::exit]]
   export fn example() void = {
           // ...
   };

You can reference entire modules with ``[[module::]]``, using a trailing
namespace separator (``::``).

Bulleted lists
~~~~~~~~~~~~~~

You may add a bulleted list by opening each line with "-", ending with an empty
line, like so:

.. code-block:: hare

   // This is a list:
   //
   // - foo
   // - bar
   // - baz
   //
   // It has three items.
   export fn example() void = {
           // ...
   };

Code samples
~~~~~~~~~~~~

You can add code samples to your documentation by prefixing each line with at
least two whitespace characters, or at least one tab character:

.. code-block:: hare

   // This is a code sample:
   //
   //   let x = 1337;
   //   example(x);
   //
   // It is simply indented from the body of the comment.
   export fn example() void = {
           // ...
   };

README
~~~~~~

You may include a file in your module directory named "README" to provide an
introduction to your module, using the same markup format as documentation
comments.