The user interface consists of several environments (the aldordoc sections). The sections should appear in the following order.
The following code is partly inspired by the implementation of ∖list in the file latex.ltx of LATEX2ɛ and partly by the aldoc package of Niklaus Mannhart.
Inside the sections the following commands are available in order to refer to the place of definition of types and functions. In fact, these commands are allowed anywhere in the text if the aldordoc package is included. They print the corresponding identifier in the running text and generate a reference (hyperlink) to its definition.
Sometimes it is necessary to cite little pieces of Aldor code inside running text. The aldordoc package provides the following.
Note that the adusage environment is like the adsnippet environment with the section heading Usage.
From the information given in an adusage environment a potential user of the function, constant, domain, package, or category should be able to use the described element in other contexts. Therefore, the adusage section should be seen as a place to give a short piece of Aldor code that demonstrates one or more common uses of the described element.
Function parameters should correspond to the names that are described in the environments addescription and adparameters.
This section is intended to describe the parameters of a function or a type constructor.
The Aldor compiler in version 1.0.2 does not compile constructions like the following piece of code.
#include "aldor"
define Cat: Category == with { func: ( a: MachineInteger, ++ Documentation for the parameter a b: MachineInteger ++ Documentation for the parameter b ) -> MachineInteger; } |
It is, therefore, impossible to attach documentation to function parameters directly. However, even if it were possible, it would, for example, remain impossible to get a parameter name for the first parameter of the function in a construction like this.
define Cat: Category == with {
func: (MachineInteger, MachineInteger) -> MachineInteger; } |
We suggest that the name of a parameter is introduced in the adusage section corresponding to the function and shortly described in an adparameters section. Currently, we completely ignore the corresponding code part17 and give the name and type of a parameter explicitly in the documentation in the following form
\begin{adparameters}
\adparameter{param1: TYPE1} Description 1 \adparameter{param2: TYPE2} Description 2 ... \end{adparameters} |
where param1 is a parameter name and TYPE1 its type. The description would usually be quite short (one-liner) and explain the role of the parameter. The identifiers param1 and param2 should correspond to variables with the same name as appearing in the adusage environment. The documentation about the relations of the parameters should be given in an addescription environment.
\begin{adusage}
c := foo(a, b) \end{adusage} |
then you would usually describe a, b, and also c in an adparameters environment.
The argument of the command ∖adparameter can contain any character. It is not necessary to escape LATEX special characters. The only restriction is that the braces { and } must be balanced.
MyCat with {
foo1: (A, B) -> %; foo2: % -> Integer; } |
The general idea is to let the input appear as natural as possible, i. e., the MyCat ... expression should appear on several lines. This goal, however, conflicts with the current implementation and the corresponding Convention 18.
See the documentation of MyBinaryPowering of how one can work around the above restriction.
The command ∖adparameter is not directly implemented but rather translated to ∖adinternalparameter by the Perl script tools/aldordoc2tex.pl.nw.
The section serves as a place for the general description of what the function or type does. References to the parameters and an explanation of the result that is returned are strongly encouraged.
The environment requires a short description as an argument.
\begin{addescription}{SHORT DESCRIPTON.}
LONG DESCRIPTION. \end{addescription} |
The short as well as the long description appear in the text. The short description is usually a one-sentence-summary of the whole description. It is intended to appear, for example, in the list of exports of a category. In contrast to aldoc, such an export list is generated automatically.
Additionally, the macros ∖adthisname and ∖adthistype are not valid here.
For functions and constants, the short description should start with a verb phrase similar to the following examples.
\begin{addescription}{Returns the square root of its argument.}
... \end{addescription} |
\begin{addescription}{Removes the first element from the list.}
... \end{addescription} |
The contents of an addescription environment should be as complete as possible. In particular it should contain further descriptions of use of the parameters that are given through the adparameters environment.
The macros ∖adthisname and ∖adthistype cannot be used in the short description since the short description might be used in other contexts where no clear reference to the currently defined name or type can be made. Therefore, we redefine those commands so that a library documentation writer is reminded of this problem.
The environment adshortdescription makes no sense for library documentation writers, but it is used for the automatic generation of the exports list of a type that also shows a short description of the function. See tools/showexports2aldordoc.pl.nw for more information.
This section is intended to list all the possible exceptions a function could throw. To each exception a short explanation should be given of when the exceptions is thrown.
It is used in the following way.
\begin{adexceptions}
\adthrows{ArrayOutOfBoundsException} if the lower index is smaller than 1 or the upper index is bigger than 9. \end{adexceptions} |
The commands ∖adthisexception and ∖adthisexceptionname are similar to ∖adthistype and ∖adthistypename. The command ∖adthrows introduces a new exception inside an adexceptions environment.
This section is to be used for additional remarks. For example, a note that the function is destructive18 should be stated inside an adremarks environment. In particular, it should be explained which input parameter is destroyed.
This section is intended to list a number of links to related functions, categories, domains or packages. Although the format is completely free, it should be used as follows.
\begin{adseealso}
\adname{foo: Integer -> ()} \adname{bar} \adtype{MyCategory} \end{adseealso} |
Instead of the two aldoc commands ∖altype and ∖alexttype, we only define ∖adtype. This command belongs to the set of active commands listed in Section 26.4.
In a library documentation one should use
\adtype{TYPE}
|
where TYPE is the name of a category, a domain, or a package.
The the above command will typeset TYPE in the running text and add an index entry and link information to the place where TYPE has been defined.
Inside the braces of ∖adtype no special character is allowed. In fact, the argument must match Convention 26. In particular, only the name of a type should be tagged by ∖adtype. Parentheses and parameters are not part of the type name.
Because of the above convention, there is no need to specify the library where the type is defined as in aldoc’s ∖alexttype. In fact, due to post-facto extensions that are available in the Aldor language, it is even not clear which library one would have to specify. For example, the domain MachineInteger is defined in the library Aldor and extended in the library Algebra. For the documentation we take the view that there is only one domain MachineInteger. Either some scripts or even the Aldor compiler should take care of providing a link to the full documentation of the corresponding type even if the documentation is actually split over several files.
The target corresponding to ∖adtype has to be specified by the ∖addefinetype command. ALLPROSE generates such a definition automatically through tools/addaldortypedef.pl.nw.
Since the argument of ∖adtype must follow Convention 26, we can define it in a very simple manner.
Similarly, instead of the two aldoc commands ∖alfunc and ∖alexp, we introduce just one command, namely ∖adname. It is intended for function and constant names.
This command belongs to the set of active commands listed in Section 26.4.
The command ∖adname takes one optional argument, the type of the origin of the name. This type defaults to ∖adthistype if it is not given.
In a library documentation one should use one of the following.
\adname[TYPE]{FUNC:SIGNATURE}
\adname[TYPE]{FUNC} \adname{FUNC:SIGNATURE} \adname{FUNC} |
The signature after the first colon is optional and should only be given if the function or constant FUNC appears somewhere in the code of TYPE also with a different signature. The idea for including the signature comes from the wish to disambiguate links as much as possible.
The type TYPE names the category, domain, or package where the function FUNC is defined.
The command ∖adname is meant to typeset FUNC in the text and provide enough information (like TYPE and SIGNATURE) in order to generate a correct link to where FUNC is actually defined. The signature SIGNATURE is not printed in text.
See ∖adinternalusename.
Instead of the aldoc commands ∖shortthis, ∖this, ∖name, and ∖thistype, we only define ∖adthistype and ∖adthisname where ∖adthistype expands to the type name that was most recently introduced and ∖adthisname typesets the most recent function or constant of the most recently introduced type.
The commands ∖adthistype and ∖adthisname belong to the set of active commands listed in Section 26.4.
The command ∖adthistypename holds the current name of the type. It will be updated by the commands ∖addescribetype and ∖addefinetype.
The command ∖adthisname is updated by ∖addefinename.
Note that the commands ∖addefinetype and ∖addefinename together with appropriate arguments are generated by a script from the source code and need not be entered by a library documentation writer.
Although we do not require the xspace LATEX package, we have added the command ∖xspace above in order to let ∖adthistype produce a (conditional) space after its expansion if the xspace package is included.
The environment adsnippet and the command ∖adcode are used to typeset pieces of Aldor code. The contents of adsnippet as well as the argument of ∖adcode are somewhat special. Write as if you were inside a verbatim environment. One difference to a verbatim environment or the ∖verb command is that there is a set of aldordoc active commands that retain their meaning, see Section 26.4. All LATEX special characters that are not connected to aldordoc active commands are escaped appropriately.
Another difference is the indentation. The first line in an adsnippet or adusage environment determines the base of the indentation, i. e., the whole environment is moved to the left by as many places as there are initial spaces on the first line.
So the following two examples result in identical output.
\begin{addescription}{Returns the square root of its argument.}
\begin{adsnippet} a := x * x; b := sqrt a; assert(a = b); \end{adsnippet} \end{addescription} |
\begin{addescription}{Returns the square root of its argument.}
\begin{adsnippet} a := x * x; b := sqrt a; assert(a = b); \end{adsnippet} \end{addescription} |
The background color of an adsnippet environment can be configured via the commands ∖backgroundColor{adsnippet}{...} at a local customization (see Section 24.12).
At the moment ∖adcode is nearly like ∖verb. But we want a similar behavior to the adsnippet environment. In fact, there is a similarity to LATEX’s ∖verb command. For example, one can write
\adcode’if \adname{zero?}(a) then ...’
|
or
\adcode|if \adname{zero?}(a) then ...|
|
in order to place a piece of code inside running text. If the argument of ∖adcode does not contain braces, it is allowed to write
\adcode{if a < b then a else b;}
|
but the form similar to ∖verb is preferred.
Note, however, that ∖adcode is as restricted as ∖verb, i. e., it cannot appear as an argument of another LATEX command.
It is quite natural to typeset code in typewriter mode. In fact, due to the definition of ∖adcode and the environments adsnippet and adusage, it is currently unwise to use any other font.
Because the command ∖textbackslash does not look like a backslash in verbatim mode, we define a special command ∖adbackslash which does.