GAP (AutoDoc) - Chapter 2: AutoDoc documentation comments

Goto Chapter: Top 1 2 3 4 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

2 AutoDoc documentation comments
2.1 Documenting declarations
2.1-1 `@Description descr`
2.1-2 `@Returns ret_val`
2.1-3 `@Arguments args`
2.1-4 `@Group grpname`
2.1-5 `@Label label`
2.1-6 AProperty
2.1-7 AProperty
2.1-8 `@ChapterInfo chapter, section`
2.2 Other documentation comments
2.2-1 `@Chapter name`
2.2-2 `@Section name`
2.2-3 `@Subsection name`
2.2-4 `@BeginGroup [grpname]`
2.2-5 `@EndGroup`
2.2-6 @GroupTitle title
2.2-7 `@Level lvl`
2.2-8 `@ResetLevel`
2.2-9 `@BeginExample` and `@EndExample`
2.2-10 `@BeginExampleSession` and `@EndExampleSession`
2.2-11 `@BeginLog` and `@EndLog`
2.2-12 `@BeginLogSession` and `@EndLogSession`
2.2-13 `@DoNotReadRestOfFile`
2.2-14 `@BeginChunk name`, `@EndChunk`, and `@InsertChunk name`
2.2-15 `@BeginCode name`, @EndCode, and `@InsertCode name`
2.2-16 `@LatexOnly text`, `@BeginLatexOnly`, and `@EndLatexOnly`
2.2-17 `@NotLatex text`, `@BeginNotLatex`, and `@EndNotLatex`
2.3 Title page commands
2.4 Plain text files
2.5 Grouping
2.5-1 A family of operations
2.6 Level
2.7 Markdown-like formatting of text in AutoDoc
2.7-1 Lists
2.7-2 Math modes
2.7-3 Emphasize
2.7-4 Inline code
2.8 Deprecated commands

### 2 AutoDoc documentation comments

You can document declarations of global functions and variables, operations, attributes etc. by inserting AutoDoc comments into your sources before these declaration. An AutoDoc comment always starts with `#!`. This is also the smallest possible AutoDoc command. If you want your declaration documented, just write `#!` at the line before the documentation. For example:

    #!
    DeclareOperation( "AnOperation",
                      [ IsList ] );

This will produce a manual entry for the operation `AnOperation`.

Inside of AutoDoc comments, AutoDoc commands starting with `@` can be used to control the output AutoDoc produces.

#### 2.1 Documenting declarations

In the bare form above, the manual entry for `AnOperation` will not contain much more than the name of the operation. In order to change this, there are several commands you can put into the AutoDoc comment before the declaration. Currently, the following commands are provided:

##### 2.1-1 `@Description descr`

Adds the text in the following lines of the AutoDoc to the description of the declaration in the manual. Lines are until the next AutoDoc command or until the declaration is reached.

##### 2.1-2 `@Returns ret_val`

The string ret_val is added to the documentation, with the text "Returns: " put in front of it. This should usually give a brief hint about the type or meaning of the value retuned by the documented function.

##### 2.1-3 `@Arguments args`

The string args contains a description of the arguments the function expects, including optional parts, which are denoted by square brackets. The argument names can be separated by whitespace, commas or square brackets for the optional arguments, like "grp[, elm]" or "xx[y[z] ]". If GAP options are used, this can be followed by a colon : and one or more assignments, like "n[, r]: tries := 100".

##### 2.1-4 `@Group grpname`

Adds the following method to a group with the given name. See section 2.5 for more information about groups.

##### 2.1-5 `@Label label`

Adds label to the function as label. If this is not specified, then for declarations that involve a list of input filters (as is the case for `DeclareOperation`, `DeclareAttribute`, etc.), a default label is generated from this filter list.

    #! @Label testlabel
    DeclareProperty( "AProperty",
                     IsObject );

leads to this:

##### 2.1-6 AProperty

`‣ AProperty`( arg ) | ( property )

Returns: `true` or `false`

while

    #!
    DeclareProperty( "AProperty",
                     IsObject );

leads to this:

##### 2.1-7 AProperty

`‣ AProperty`( arg ) | ( property )

Returns: `true` or `false`

##### 2.1-8 `@ChapterInfo chapter, section`

Adds the entry to the given chapter and section. Here, chapter and section are the respective titles.

As an example, a full AutoDoc comment with all options could look like this:

    #! @Description
    #! Computes the list of lists of degrees of ordinary characters
    #! associated to the $p$-blocks of the group $G$
    #! with $p$-modular character table <A>modtbl</A>
    #! and underlying ordinary character table `ordtbl`.
    #! @Returns a list
    #! @Arguments modtbl
    #! @Group CharacterDegreesOfBlocks
    #! @Label chardegblocks
    #! @ChapterInfo Blocks, Attributes
    DeclareAttribute( "CharacterDegreesOfBlocks",
            IsBrauerTable );

#### 2.2 Other documentation comments

There are also some commands which can be used in AutoDoc comments that are not associated to any declaration. This is useful for additional text in your documentation, examples, mathematical chapters, etc..

##### 2.2-1 `@Chapter name`

Sets the active chapter, all subsequent functions which do not have an explicit chapter declared in their AutoDoc comment via `@ChapterInfo` will be added to this chapter. Also all text comments, i.e. lines that begin with #! without a command, and which do not follow after `@Description`, will be added to the chapter as regular text. Additionally, the chapters label wil be set to `Chapter_`name. Example:

    #! @Chapter My chapter
    #!  This is my chapter.
    #!  I document my stuff in it.

The `@ChapterLabel` label command can be used to set the label of the chapter to `Chapter_`label instead of `Chapter_`name. Additionally, the chapter will be stored as `_Chapter_`label`.xml`. The `@ChapterTitle` title command can be used to set a heading for the chapter that is different from name. Note that the title does not affect the label. If you use all three commands, i.e.,

    #! @Chapter name
    #! @ChapterLabel label
    #! @ChapterTitle title

`title` is used for the headline, `label` for cross-referencing, and `name` for setting the same chapter as active chapter again.

##### 2.2-2 `@Section name`

Sets an active section like `@Chapter` sets an active chapter. The section automatically ends with the next `@Section` or `@Chapter` command.

    #! @Section My first manual section
    #!  In this section I am going to document my first method.

The `@SectionLabel` label command can be used to set the label of the section to `Section_`label instead of `Chapter_chaptername_Section_`name. The `@SectionTitle` title command can be used to set a heading for the section that is different from name.

##### 2.2-3 `@Subsection name`

Sets an active subsection like `@Section` sets an active section. The subsection automatically ends with the next `@Subsection`, `@Section` or `@Chapter` command. It also ends with the next documented function. Indeed, internally each function "manpage" is treated like a subsection.

    #! @Subsection My first manual subsection
    #!  In this subsection I am going to document my first example.

The `@SubsectionLabel` label command can be used to set the label of the subsection to `Subsection_`label instead of `Chapter_chaptername_Section_sectionname_Subsection_`name. The `@SubsectionTitle` title command can be used to set a heading for the subsection that is different from name.

##### 2.2-4 `@BeginGroup [grpname]`

Starts a group. All following documented declarations without an explicit `@Group` command are grouped together in the same group with the given name. If no name is given, then a new nameless group is generated. The effect of this command is ended when an `@EndGroup` command is reached.

See section 2.5 for more information about groups.

##### 2.2-5 `@EndGroup`

Ends the current group.

    #! @BeginGroup MyGroup
    #!
    DeclareAttribute( "GroupedAttribute",
                      IsList );

    DeclareOperation( "NonGroupedOperation",
                      [ IsObject ] );

    #!
    DeclareOperation( "GroupedOperation",
                      [ IsList, IsRubbish ] );
    #! @EndGroup

##### 2.2-6 @GroupTitle title

Sets the subsection heading for the current group to title. In the absence of any `@GroupTitle` command, the heading will be the name of the first entry in the group. See 2.5 for more information.

##### 2.2-7 `@Level lvl`

Sets the current level of the documentation. All items created after this, chapters, sections, and items, are given the level lvl, until the `@ResetLevel` command resets the level to 0 or another level is set.

See section 2.6 for more information about levels.

##### 2.2-8 `@ResetLevel`

Resets the current level to 0.

##### 2.2-9 `@BeginExample` and `@EndExample`

`@BeginExample` marks the start of an example to be put into the manual. It differs from GAPDoc's `<Example>` (see GAPDoc: Log), in that it expects actual code (not in a comment) interspersed with comments, to allow for examples files that can be both executed by GAP, and parsed by AutoDoc. To achieve this, GAP commands are not preceded by a comment, while output has to be preceded by an AutoDoc comment. The `gap>` prompt for the display in the manual is added by AutoDoc. `@EndExample` ends the example block.

To illustrate this command, consider this input:

    #! @BeginExample
    S5 := SymmetricGroup(5);
    #! Sym( [ 1 .. 5 ] )
    Order(S5);
    #! 120
    #! @EndExample

This results in the following output:

    gap> S5 := SymmetricGroup(5);
    Sym( [ 1 .. 5 ] )
    gap> Order(S5);
    120

The AutoDoc command `@Example` is an alias of `@BeginExample`.

##### 2.2-10 `@BeginExampleSession` and `@EndExampleSession`

`@BeginExampleSession` marks the start of an example to be put into the manual, while `@EndExampleSession` ends the example block. It is the direct analog of GAPDoc's `<Example>` (see GAPDoc: Log).

To illustrate this command, consider this input:

    #! @BeginExampleSession
    #! gap> S5 := SymmetricGroup(5);
    #! Sym( [ 1 .. 5 ] )
    #! gap> Order(S5);
    #! 120
    #! @EndExampleSession

This results in the following output:

    gap> S5 := SymmetricGroup(5);
    Sym( [ 1 .. 5 ] )
    gap> Order(S5);
    120

It inserts an example into the manual just as `@Example` would do, but all lines are commented and therefore not executed when the file is read. All lines that should be part of the example displayed in the manual have to start with an AutoDoc comment (`#!`). The comment will be removed, and, if the following character is a space, this space will also be removed. There is never more than one space removed. To ensure examples are correctly colored in the manual, there should be exactly one space between `#!` and the `gap>` prompt. The AutoDoc command `@ExampleSession` is an alias of `@BeginExampleSession`.

##### 2.2-11 `@BeginLog` and `@EndLog`

Works just like the `@BeginExample` command, but the example will not be tested. See the GAPDoc manual for more information. The AutoDoc command `@Log` is an alias of `@BeginLog`.

##### 2.2-12 `@BeginLogSession` and `@EndLogSession`

Works just like the `@BeginExampleSession` command, but the example will not be tested if manual examples are run. It is the direct analog of GAPDoc's `<Log>` (see GAPDoc: Log). The AutoDoc command `@LogSession` is an alias of `@BeginLogSession`.

##### 2.2-13 `@DoNotReadRestOfFile`

Prevents the rest of the file from being read by the parser. Useful for unfinished or temporary files.

    #! This will appear in the manual

    #! @DoNotReadRestOfFile

    #! This will not appear in the manual.

##### 2.2-14 `@BeginChunk name`, `@EndChunk`, and `@InsertChunk name`

Text inside a `@BeginChunk` / `@EndChunk` part will not be inserted into the final documentation directly. Instead, the text is stored in an internal buffer. That chunk of text can then later on be inserted in any other place by using the `@InsertChunk name` command. If you do not provide an `@EndChunk`, the chunk ends at the end of the file.

    #! @BeginChunk MyChunk
    #! Hello, world.
    #! @EndChunk

    #! @InsertChunk MyChunk
    ## The text "Hello, world." is inserted right before this.

You can use this to define an example like this in one file:

    #! @BeginChunk Example_Symmetric_Group
    #! @BeginExample
    S5 := SymmetricGroup(5);
    #! Sym( [ 1 .. 5 ] )
    Order(S5);
    #! 120
    #! @EndExample
    #! @EndChunk

And then later, insert the example in a different file, like this:

    #! @InsertChunk Example_Symmetric_Group

##### 2.2-15 `@BeginCode name`, @EndCode, and `@InsertCode name`

Inserts the text between `@BeginCode` and `@EndCode` verbatim at the point where `@InsertCode` is called. This is useful to insert code excerpts directly into the manual.

    #! @BeginCode Increment
    i := i + 1;
    #! @EndCode

    #! @InsertCode Increment
    ## Code is inserted here.

##### 2.2-16 `@LatexOnly text`, `@BeginLatexOnly`, and `@EndLatexOnly`

Code inserted between `@BeginLatexOnly` and `@EndLatexOnly` or after `@LatexOnly` is only inserted in the PDF version of the manual or worksheet. It can hold arbitrary LaTeX-commands.

    #! @BeginLatexOnly
    #! \include{picture.tex}
    #! @EndLatexOnly

    #! @LatexOnly \include{picture.tex}

##### 2.2-17 `@NotLatex text`, `@BeginNotLatex`, and `@EndNotLatex`

Code inserted between `@BeginNotLatex` and `@EndNotLatex` or after `@NotLatex` is inserted in the HTML and text versions of the manual or worksheet, but not in the PDF version.

    #! @BeginNotLatex
    #! For further information see the PDF version of this manual.
    #! @EndNotLatex

    #! @NotLatex For further information see the PDF version of this manual.

#### 2.3 Title page commands

The following commands can be used to add the corresponding parts to the title page of the document which generated by AutoDoc if scaffolding is enabled.

- `@Title`

- `@Subtitle`

- `@Version`

- `@TitleComment`

- `@Author`

- `@Date`

- `@Address`

- `@Abstract`

- `@Copyright`

- `@Acknowledgements`

- `@Colophon`

Those add the following lines at the corresponding point of the title page. Please note that many of those things can be (better) extracted from the `PackageInfo.g`. In case you set some of those, the extracted or in scaffold defined items will be overwritten. While this is not very useful for documenting packages, they are necessary for worksheets created with `AutoDocWorksheet` (3.1-1), since worksheets do not have a `PackageInfo.g` file from which this information could be extracted.

#### 2.4 Plain text files

Files that have the suffix `.autodoc` and are listed in the `autodoc.files` option of `AutoDoc` (4.1-1), resp. are contained in one of the directories listed in `autodoc.scan_dirs`, are treated as AutoDoc plain text files. These work exactly like AutoDoc comments, except that lines do not need to (and in fact, should not) start with `#!`.

#### 2.5 Grouping

In GAPDoc, it is possible to make groups of manual items, i.e., when documenting a function, operation, etc., it is possible to group them into suitable chunks. This can be particularly useful if there are several definitions of an operation with several different argument types, all doing more or less the same to the arguments. Then their manual items can be grouped, sharing the same description and return type information. You can give a heading to the group in the manual with the `@GroupTitle` command; if that is not supplied, then the heading of the first manual item in the group will be used as the heading.

Note that group names are globally unique throughout the whole manual. That is, groups with the same name are in fact merged into a single group, even if they were declared in different source files. Thus you can have multiple `@BeginGroup` / `@EndGroup` pairs using the same group name, in different places, and these all will refer to the same group.

Moreover, this means that you can add items to a group via the `@Group` command in the AutoDoc comment of an arbitrary declaration, at any time.

The following code

    #! @BeginGroup Group1
    #! @GroupTitle A family of operations

    #! @Description
    #!  First sentence.
    DeclareOperation( "FirstOperation", [ IsInt ] );

    #! @Description
    #!  Second sentence.
    DeclareOperation( "SecondOperation", [ IsInt, IsGroup ] );

    #! @EndGroup

    ## .. Stuff ..

    #! @Description
    #!  Third sentence.
    #! @Group Group1
    KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime );

produces the following:

##### 2.5-1 A family of operations

`‣ FirstOperation`( arg ) | ( operation )

`‣ SecondOperation`( arg1, arg2 ) | ( operation )

`‣ ThirdOperation`( arg1, arg2 ) | ( operation )

First sentence. Second sentence. Third sentence.

#### 2.6 Level

Levels can be set to not write certain parts in the manual by default. Every entry has by default the level 0. The command `@Level` can be used to set the level of the following part to a higher level, for example 1, and prevent it from being printed to the manual by default. However, if one sets the level to a higher value in the autodoc option of AutoDoc, the parts will be included in the manual at the specific place.

    #! This text will be printed to the manual.
    #! @Level 1
    #! This text will be printed to the manual if created with level 1 or higher.
    #! @Level 2
    #! This text will be printed to the manual if created with level 2 or higher.
    #! @ResetLevel
    #! This text will be printed to the manual.

#### 2.7 Markdown-like formatting of text in AutoDoc

AutoDoc has some convenient ways to insert special format into text, like math formulas and lists. The syntax for them are inspired by Markdown and LaTeX, but do not follow them strictly. Neither are all features of the Markdown language supported. The following subsections describe what is possible.

##### 2.7-1 Lists

One can create lists of items by beginning a new line with *, +, -, followed by one space. The first item starts the list. When items are longer than one line, the following lines have to be indented by at least two spaces. The list ends when a line which does not start a new item is not indented by two spaces. Of course lists can be nested. Here is an example:

    #! The list starts in the next line
    #! * item 1
    #! * item 2
    #!   which is a bit longer
    #!   * and also contains a nested list
    #!   * with two items
    #! * item 3 of the outer list
    #! This does not belong to the list anymore.

This is the output:
The list starts in the next line

- item 1

- item 2 which is a bit longer

  - and also contains a nested list

  - with two items

- item 3 of the outer list

This does not belong to the list anymore.
The *, -, and + are fully interchangeable and can even be used mixed, but this is not recommended.

##### 2.7-2 Math modes

One can start an inline formula with a $, and also end it with $, just like in LaTeX. This will translate into GAPDocs inline math environment. For display mode one can use $$, also like LaTeX.

    #! This is an inline formula: $1+1 = 2$.
    #! This is a display formula:
    #! $$ \sum_{i=1}^n i. $$

produces the following output:
This is an inline formula: \(1+1 = 2\). This is a display formula:

\[ \sum_{i=1}^n i. \]

##### 2.7-3 Emphasize

One can emphasize text by using two asterisks (**) or two underscores (__) at the beginning and the end of the text which should be emphasized. Example:

    #! **This** is very important.
    #! This is __also important__.
    #! **Naturally, more than one line
    #! can be important.**

This produces the following output:
This is very important. This is also important. Naturally, more than one line can be important.

##### 2.7-4 Inline code

One can mark inline code snippets by using backticks (`) at the beginning and the end of the text which should be marked as code. Example:

    #! Call function `foobar()` at the start.

This produces the following output:
Call function `foobar()` at the start.

#### 2.8 Deprecated commands

The following commands used to be supported, but should not generally be used anymore. They will be removed in a future version of AutoDoc.

`@EndSection`

  You can simply remove any use of this, AutoDoc ends sections automatically at the start of any new section or chapter.

`@EndSubsection`

  You can simply remove any use of this, AutoDoc ends subsections automatically at the start of any new subsection, section or chapter.

`@BeginAutoDoc` and `@EndAutoDoc`

  It suffices to prepend each declaration that is meant to be appear in the manual with a minimal AutoDoc comment `#!`.

`@BeginSystem name`, `@EndSystem`, and `@InsertSystem name`

  Please use the chunk commands from subsection 2.2-14 instead.

`@AutoDocPlainText` and `@EndAutoDocPlainText`

  Use `.autodoc` files or AutoDoc comments instead.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 Bib Ind

generated by GAPDoc2HTML