25.2 User Interface

  25.2.1 The aldordoc Section adusage
  25.2.2 The aldordoc Section adparameters
  25.2.3 The aldordoc Section addescription
  25.2.4 The aldordoc Section adexceptions
  25.2.5 The aldordoc Section adremarks
  25.2.6 The aldordoc Section adseealso
  25.2.7 The adtype command
  25.2.8 The adname command
  25.2.9 The adthistype and adthisname commands
  25.2.10 The adsnippet environment and the adcode command
  25.2.11 The Code Font

The user interface consists of several environments (the aldordoc sections). The sections should appear in the following order.

  1. \begin{adusage} ... \end{adusage}: Section for describing the usage of a function, constant or type.
  2. \begin{adparameters} ... \end{adparameters} (optional): Section for describing function parameters.
  3. \begin{addescription}{SHORT DESCRIPTON} ... \end{addescription}: Section for describing the function, constant, or type more clearly.
  4. \begin{adexceptions} ... \end{adexceptions} (optional): Section for describing which exceptions the function throws.
  5. \begin{adremarks} ... \end{adremarks} (optional): Section for describing particular behavior like, for example, destructiveness of a function.
  6. \begin{adseealso} ... \end{adseealso} (optional): Section for pointing to related things.

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.

250user interface 250  (247)  252
\newenvironment{adsection}[1]{%
  \pagebreak[2]\par\noindent\textbf{#1}\nopagebreak\par
  \parindent0pt\parskip\smallskipamount
  \leftmargin3ex\advance\linewidth -\leftmargin
  \advance\@totalleftmargin \leftmargin
  \parshape \@ne \@totalleftmargin \linewidth}{\par\medskip}%

\newenvironment{aditemsection}[1]{%
  \pagebreak[2]\par\noindent\textbf{#1}\nopagebreak\par
  \begin{list}{}{%
      \setlength{\leftmargin}{6ex}\setlength{\itemindent}{-3ex}%
      \setlength{\parsep}{0pt}\setlength{\partopsep}{0pt}%
      \setlength{\topsep}{0pt}\setlength{\itemsep}{0pt}%
      \setlength{\labelwidth}{0pt}\setlength{\labelsep}{0pt}%
    }}{\end{list}\medskip}%

Defines:
aditemsection, used in chunks 230, 257, and 263.
adsection, used in chunks 252, 260, 264, 265, 481, and 482.

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.

25.2.1 The aldordoc Section adusage

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.

252user interface 250+   (247)  250  257
\newenvironment{adusage}%
  {\begin{adsection}{Usage}}%
  {\end{adsection}}

Defines:
adusage, never used.

Uses adsection 250.

25.2.2 The aldordoc Section 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.

ToDo 11 The environment adparameters should be used for input and output, i. e., if you write
\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.

ToDo 12 There appears to be a design problem for the case when TYPE1 is a category expression like for example
    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.

257user interface 250+   (247)  252  260
\newenvironment{adparameters}%
  {\begin{aditemsection}{Parameters}}{\end{aditemsection}}

Defines:
adparameters, never used.

Uses aditemsection 250.
25.2.3 The aldordoc Section addescription

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.

Convention 16 Since the short description of an addescription environment is used in other places, it should not make any references to named parameters.

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.

260user interface 250+   (247)  257  261a
\newenvironment{addescription}[1]%
  {\begin{adsection}{Description}\begingroup
    \let\adthisname\adshortthisname
    \let\adthistype\adshortthistype
    #1\endgroup\par}%
  {\end{adsection}}

Defines:
addescription, used in chunk 496.

Uses adsection 250, adshortthisname 261b, and adshortthistype 261b.

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.

261auser interface 250+   (247)  260  261b
\newenvironment{adshortdescription}[1]%
  {\begingroup
    \let\adthisname\adshortthisname
    \let\adthistype\adshortthistype
    #1\endgroup\comment}%
  {\endcomment}

Defines:
adshortdescription, never used.

Uses adshortthisname 261b and adshortthistype 261b.
261buser interface 250+   (247)  261a  263
\newcommand{\adshortproblem}[1]{\par\textbf{\fbox{aldordoc warning}
    You should not use \usetexcommand{adthis#1} in a short description
    since the short description is also used in other contexts where
    it is not clear what \usetexcommand{adthis#1} refers to. You must
    give the appropriate #1 explicitly. Rewrite
    \usetexcommand{adthis#1} into \usetexcommand{ad#1}\{#1\}.}\par}
\newcommand{\adshortthisname}{\adshortproblem{name}}
\newcommand{\adshortthistype}{\adshortproblem{type}}

Defines:
adshortthisname, used in chunks 260 and 261a.
adshortthistype, used in chunks 260 and 261a.

25.2.4 The aldordoc Section adexceptions

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.

263user interface 250+   (247)  261b  264
\newenvironment{adexceptions}%
  {\begin{aditemsection}{Throws}}{\end{aditemsection}}
\newcommand{\adthisexception}{\adtype{\adthisexceptionname}}
\newcommand{\adthisexceptionname}{}
\newcommand{\adthrows}[1]{\item
  \renewcommand{\adthisexceptionname}{#1}\adthisexception{}}

Defines:
adexceptions, never used.

Uses aditemsection 250.

25.2.5 The aldordoc Section adremarks

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.

264user interface 250+   (247)  263  265
\newenvironment{adremarks}%
  {\begin{adsection}{Remarks}}{\end{adsection}}

Defines:
adremarks, never used.

Uses adsection 250.
25.2.6 The aldordoc Section adseealso

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}

265user interface 250+   (247)  264  266
\newenvironment{adseealso}%
  {\begin{adsection}{See also}}{\end{adsection}}

Defines:
adseealso, never used.

Uses adsection 250.

25.2.7 The adtype command

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.

Convention 17 Although possible in Aldor, we discourage overloading of category, domain and package names. In a given set of libraries the constructor names should be unique in the sense that there are no two (domain, package, category) constructor definitions with the same name but different signature.

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.

266user interface 250+   (247)  265  268
\newcommand{\adtype}[1]{%
  \@ifundefined{r@!#1}% corresponds to \label{!#1} above
    {\adtypeStyle{\adcodefont{#1}}}%
    {\hyperlink{dt:#1}{\adtypeStyle{\adcodefont{#1}}}}%
  \index{#1@\protect\adcodefont{#1}}%
}
\newcommand{\adtypeStyle}[1]{#1}

Defines:
adtypeStyle, used in chunk 390.

25.2.8 The adname command

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.

25.2.9 The adthistype and adthisname commands

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.

268user interface 250+   (247)  266  269
\newcommand{\adthistype}{\adtype{\adthistypename}\xspace}
\newcommand{\adthistypename}{}% the type name that is currently described
\newcommand{\adthisname}{}% name of the current function or constant

Uses xspace 269.

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.

269user interface 250+   (247)  268  271
\@ifundefined{xspace}{\def\xspace{\relax}}{}

Defines:
xspace, used in chunks 268 and 286.

25.2.10 The adsnippet environment and the adcode command
ToDo 13 Think of using the listings package
http://www.tug.org/tex-archive/macros/latex/contrib/listings in particular in connection with tagging identifiers, i. e., at least adtype should not appear inside the code but rather as an optional argument to the adsnippet environment.

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).

271user interface 250+   (247)  269  274a
\def\backgroundadsnippet{}
\newenvironment{adsnippet}{%
  \begin{ColoredBackground}{adsnippet}\footnotesize
  \begin{list}{}{%
    \setlength{\leftmargin}{0pt}\setlength{\rightmargin}{0pt}%
    \setlength{\labelwidth}{0pt}\setlength{\labelsep}{0pt}%
    \setlength{\parsep}{0pt}\setlength{\partopsep}{0pt}%
    \setlength{\topsep}{0pt}\setlength{\itemsep}{0pt}%
  }\item}%
  {\end{list}\end{ColoredBackground}}

Uses ColoredBackground 202.

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.

25.2.11 The Code Font

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.

274auser interface 250+   (247)  271  274b
\newcommand{\adcodefont}{\texttt}

Because the command textbackslash does not look like a backslash in verbatim mode, we define a special command adbackslash which does.

274buser interface 250+   (247)  274a  287
\newcommand{\adbackslash}{\adcodefont{\char‘\\}}