How To Document Frege Source

Source code documentation comments

As detailed in the language reference section 2.3.1, documentation comments are actually tokens and as such part of the syntax. They may appear in the following places:

1. before the package or module keyword. This will be the module documentation.
2. in place of a top level declaration or a declaration in the where clause of a data, class or instance declaration. It can also appear immediately before such a declaration. This will be the documentation for the subsequent declared item.
3. immediately either before or after a constructor in a data declaration. This will be the documentation for that constructor.
4. immediately before or after a constructor field. In the latter case, no comma must be written before the next constructor field.

In cases 1 and 2, one can write as many documentation comments as one wants. In cases 3 and 4, it can be at most one.

A sequence of documentation comments will be collapsed into a single one by the compiler. The components will be separated by an empty line (which acts as a paragraph break in the currently used markdown, see below).

Here is an example that shows the possibilities:

--- this package is documented
{-- second paragraph of package doc -}
{-- 
    third paragraph of package doc
    
    4th paragraph of package doc
-}
package WithDoc where
--- this is the list of Fibonacci numbers
fib = 1:1:zipWith (+) fib (tail fib)
--- documentation for type D
data D =
    --- documentation for constructor C
    C { name :: String --- documentation for name, no comma here
        {-- documentation for age -}
       age :: Int }
   | N --- documentation for constructor N

Documentation text will be copied verbatim and it will be available in the binary results of compilation (e.g. Java class files), so that documentation processing tools can access it to generate documentation in various formats.

Markup

The following markup is supported by the documentation tool and the eclipse plugin:

*bold*  _italic_ @monospaced@ 'reference'

A reference is the (possibly qualified) name of a frege type, function, etc. This should turn to a hyperlink when processed. The reference will be resolved in the context of the package that contains the comment. What this means is that reference must be a name that would be valid on the toplevel of the package. If the name resolution fails, the text enclosed in the apostrophes will be shown in red color.

But sometimes one needs to reference something in a package that is not imported. For this, the following syntax is possible:

'some.other.Package#something'

The validity of such a reference can not be checked, of course.

Finally, if one needs a generic link, it can be written like thus:

'http://projecteuler.net/index.php?section=problems&id=12 Euler probelm 12'

The part before the first space character is taken as URL, the rest is the text that will be shown.

An empty line serves as paragraph break. Special paragraphs are

#   Header 1
##  Header 2
### Header 3
> preformatted text (i.e. code examples)
> each line must start with ">"

- unordered list item
1. ordered list item
(2) ordered list item
[item] list item tagged with "item"

Paragraphs do not nest.

Documentation in the eclipse plugin

For some reason, in the eclipse plugin, most of the markup gets lost, though the documentation processing code produces W3C conform HTML. We'll have to investigate that.

Nevertheless it is used in 2 places:

• mouse hover: when you move the mouse over any identifier, Eclipse will display the type of that item (if it has one) along with the documentation (if it has some).
• in code completion, if you browse through the list, Eclipse will display the same information.

This is extremely usable, therefore everyone writing library code is strongly encouraged to write some documentation comments here and there. Note that the comments are taken from the module class file, so they will be there even if the user does not have the source code!

Generating HTML documentation

Say you have compiled a module foo.bar.Baz and you want to generate the documentation.

java -cp frege.jar frege.tools.Doc -d doc foo.bar.Baz

This will create a file doc/foo/bar/Baz.html with useful information derived from the class file.

Please use -help to see all options and their meaning, especially how to generate the documentation not only per module but for all modules in a directory tree or in a jar file.

Even if you have no documentation comments, the documentation will still include all classes, instances, data types and top level functions, along with their types and may serve as quick overview.

The directory named after -d must exist previously, further subdirectories are created on the fly.

The generated document may contain hyperlinks to documentation of modules your module depends on. They will work under the assumption that all documentation was generated with the same target directory (-d).