8 How to Document the Aldor Sources

The Aldor source files reside under the directory src. The source code for the testsuite resides under test. And the general include files are in directory include.

ALLPROSE comes together with a sample project MyAlps. Look at the files in the src/myalps in order to get an impression of how literate Aldor sources have to be written. In particular you should consult Section 25.2 for a description of the LATEX commands you can and should use in order to structure the API description of your code.

The full power of LATEX is available for the documentation of the Aldor sources and LATEX is also used for the API (application programming interface) documentation.

For a program or library there are (at least) two types of people:

1. people who want to use the program or library, and
2. people who maintain the program or library.

Of course, different documentation is required for those people. That is why ALLPROSE supports two types of documents:

1. an API specification for users of the program or library,
2. the full documentation including the API description and the description of the actual algorithms and implementation for people who maintain the program or library.

Why a full documentation is useful for a software maintainer is rather clear. It is one of the reasons for the existence of ALLPROSE.

We do, however, believe that not everyone needs to be bothered with the implementation details. For users of the software a clear and easily browsable API documentation is of equal importance.

The API documentation in Aldor is done using the compiler feature to maintain the (so-called) ++ descriptions in compiled programs.

Ideally, there should be a tool that takes a set of .al libraries and produces a hyperlinked document out of the ++ descriptions that are compiled into the contained .ao files. Unfortunately, such a tool does not yet exist and (worse still) the libraries Aldor and Algebra do not contain nicely formatted ++ descriptions.

Nevertheless, ALLPROSE supports the API specification through Aldor ++ descriptions. Instead of writing Aldor ++ and +++ descriptions directly into a code chunk, ALLPROSE provides a +++ environment which contains LATEX code that is structured by using the aldordoc user interface as described in Section 25.2.

Such +++ environments are transformed automatically into Aldor +++ descriptions, i. e., with the +++ added at the beginning of every line, when the .as file is extracted from the .as.nw file so that this documentation is available inside the .ao files of the generated .al library. It can be extracted, from the .ao files via, for example,

into a .asy file.

As mentioned before, there is currently no tool that transforms .asy files into LATEX or HTML documentation. The program AldorDoc by Yannis Chicha aimed in that direction, but is unfortunately no longer maintained.

Remember that Aldor source files (including their directory) that form the target library must be listed via the ∖sourcefile command in myalps.tex.nw (projectname.tex) together with some minor description of what the corresponding .as file contains. See Section 4 for a template of such a listing. The file myalps.tex.nw is the only place where the names of the Aldor source files are made known to ALLPROSE. These names will be automatically extracted via the script tools/asfiles.pl.nw so that they can be used for the MAKE process. Dependencies between the sources are computed automatically via the script tools/dependencies.pl.nw.

Write the exports part of a domain, package, or category like in the following example (taken from the file src/myalps/binpow.as.nw).

In particular, do not forget the braces in the with and add part.

In order to be able to generate exports lists, ALLPROSE needs to impose some restrictions on the way the code is written. Export code chunks of the form

are covered by Conventions 23 and 21.

In case there are default implementations as, for example, in src/myalps/copy.as.nw, use the special form <<defaults: TYPENAME>> as demonstrated below.

Furthermore, the API documentation has to be written as a +++ environment immediately before the corresponding code chunk. In src/myalps/binpow.as.nw you find it in the following form.

Note that ALLPROSE transforms the above lines into

so that only one function signature per code chunk makes sense if the documentation should be attached to the code. There is no environment in ALLPROSE corresponding to ++ (post-description).

In general, there are several export code chunks that contain function definitions. If there appears an inheritance from some category, it should be inside the with clause, not before it. For Aldor both variants are semantically equivalent, but ALLPROSE imposes this restriction, in order to generate the exports list without invoking the Aldor compiler. See src/myalps/arith.as.nw for an example.

There is a command ∖showexports that includes a file (with extension .tex) in verbatim mode whose name is given by the argument of ∖showexports. During the compilation of the documentation a script filters out all ∖showexports commands that start in the first column and generates the corresponding files by running a NOTANGLE on them with a root given by the argument of ∖showexports prepended by the string “exports: ”. Thus \showexports{MyArithmeticType} would include the corresponding exports of that domain. Note that the corresponding code chunk must be of the form <<exports: MyArithmeticType>>. See also target showexports.

Note that ∖showexports imports a file only once.

Note also that most probably there is no need to write ∖showexports explicitly in the text, because these commands are added automatically by tools/addaldortypedef.pl.nw when certain conditions are met. The above code is an example where the ∖showexports command is added automatically by tools/addaldortypedef.pl.nw.

As already demonstrated in the examples above, the following conventions should be met.

For example, the package MyBinaryPowering lives in the code chunk with name <<pkg: MyBinaryPowering>>.