GAP (AutoDoc) - Chapter 2: AutoDoc documentation comments

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

[MathJax on]

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 @EndSection
2.2-4 @Subsection name
2.2-5 @EndSubsection
2.2-6 @BeginAutoDoc
2.2-7 @EndAutoDoc
2.2-8 @BeginGroup [grpname]
2.2-9 @EndGroup
2.2-10 @Level lvl
2.2-11 @ResetLevel
2.2-12 @BeginExample and @EndExample
2.2-13 @BeginLog and @EndLog
2.2-14 @DoNotReadRestOfFile
2.2-15 @BeginChunk name, @EndChunk, and @InsertChunk name
2.2-16 @BeginSystem name, @EndSystem, and @InsertSystem name
2.2-17 @BeginCode name, @EndCode, and @InsertCode name
2.2-18 @LatexOnly text, @BeginLatexOnly , and @EndLatexOnly
2.3 Title page commands
2.4 Plain text files
2.5 Grouping
2.5-1 FirstOperation
2.6 Level
2.7 Some syntax for AutoDoc text
2.7-1 Lists
2.7-2 Math modes
2.7-3 Emphasize

### 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`.

#### 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 for with all options could look like this:

    #! @Description
    #! Computes the list of lists of degrees of ordinary characters
    #! associated to the <A>p</A>-blocks of the group <A>G</A>
    #! with <A>p</A>-modular character table <A>modtbl</A>
    #! and underlying ordinary character table <A>ordtbl</A>.
    #! @Returns a list
    #! @Arguments modtbl
    #! @Group CharacterDegreesOfBlocks
    #! @FunctionLabel 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 a chapter, all functions without seperate info 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. Example:

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

##### 2.2-2 @Section name

Sets a section like chapter sets a chapter.

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

##### 2.2-3 @EndSection

Closes the current section. Please be careful here. Closing a section before opening it might cause unexpected errors.

    #! @EndSection
    #### The following text again belongs to the chapter
    #! Now we could start a second section if we want to.

##### 2.2-4 @Subsection name

Sets a subsection like chapter sets a chapter.

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

##### 2.2-5 @EndSubsection

Closes the current subsection. Please be careful here. Closing a subsection before opening it might cause unexpected errors.

    #! @EndSubsection
    #### The following text again belongs to the section
    #! Now we are in the section again

##### 2.2-6 @BeginAutoDoc

Causes all subsequent declarations to be documented in the manual, regardless of whether they have an AutoDoc comment in front of them or not.

##### 2.2-7 @EndAutoDoc

Ends the affect of `@BeginAutoDoc`. So from here on, again only declarations with an explicit AutoDoc comment in front are added to the manual.

    #! @BeginAutoDoc

    DeclareOperation( "Operation1", [ IsList ] );

    DeclareProperty( "IsProperty", IsList );

    #! @EndAutoDoc

Both, `Operation1` and `IsProperty` would appear in the manual.

##### 2.2-8 @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-9 @EndGroup

Ends the current group.

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

    DeclareOperation( "NonGroupedOperation",
                      [ IsObject ] );

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

##### 2.2-10 @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 groups.

##### 2.2-11 @ResetLevel

Resets the current level to 0.

##### 2.2-12 @BeginExample and @EndExample

@BeginExample inserts an example into the manual. The syntax is like the example enviroment in GAPDoc. This examples can be tested by GAPDoc, and also stay readable by GAP. The GAP prompt is added by AutoDoc. @EndExample ends the example block.

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

##### 2.2-13 @BeginLog and @EndLog

Works just like the @BeginExample command, but the example wont be testet. See the GAPDoc manual for more information.

##### 2.2-14 @DoNotReadRestOfFile

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

    #! This will appear in the manual

    #! @DoNotReadRestOfFile

    #! This wont.

##### 2.2-15 @BeginChunk name, @EndChunk, and @InsertChunk name

@BeginChunk causes the next documentation parts not to be inserted in the documentation at it's point in the file, but at the point where the @InsertChunk name command is. This can be used to insert examples from different files at a specific point in the documentation. A normal chunk ends at the end of the file. You can also end a system with @EndChunk.

    #! @BeginChunk MyChunk
    #! This is some text.
    #! @EndChunk

    #! @InsertChunk MyChunk
    ## Text is inserted here.

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

    #! @InsertChunk Example_Symmetric_Group

##### 2.2-16 @BeginSystem name, @EndSystem, and @InsertSystem name

Same as @BeginChunk etc. This command is deprecated. Please use chunk instead.

##### 2.2-17 @BeginCode name, @EndCode, and @InsertCode name

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

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

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

##### 2.2-18 @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.3 Title page commands

The following commands can be used to add the corresponding parts to the title page of the document, in case the scaffolding is enabled.

- @Title

- @Subtitle

- @Version

- @TitleComment

- @Author

- @Date

- @Address

- @Abstract

- @Copyright

- @Acknowledgements

- @Colophon

- @URL

Those add the following lines at the corresponding point of the titlepage. 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.

#### 2.4 Plain text files

AutoDoc plain text files work exactly like AutoDoc comments, except that the #! is unnecessary at the beginning of a line which should be documented. Files that have the suffix .autodoc will automatically regarded as plain text files while the commands @AutoDocPlainText and @EndAutoDocPlainText mark parts in plain text files which should be regarded as AutoDoc parts. All commands can be used like before.

#### 2.5 Grouping

TODO: explain more about groups and what they do, how they look in the generated output etc.

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

    #! @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 FirstOperation

`‣ 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 Some syntax for AutoDoc text

AutoDoc offers some useful syntax extensions which can be used in AutoDoc plain text files and AutoDoc comments. The syntax is inspired by the Markdown language, but it does not implement all features, neither is strict Markdown, but tries to be as straight as possible. The following constructions are possible right now:

##### 2.7-1 Lists

One can create items lists 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 curse 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 enviroment. 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 asteriks (**) 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.

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

generated by GAPDoc2HTML