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

5 The main functions
 5.1 The main function
 5.2 Global variable
 5.3 The declare functions
 5.4 The install functions
 5.5 The create functions
 5.6 Additional functions

5 The main functions

5.1 The main function

5.1-1 CreateAutomaticDocumentation
‣ CreateAutomaticDocumentation( package_name, path_to_xml_file[, section_intros] )( function )

Returns: nothing

After loading the package, run it with the name of the package you want to create a documentation of as first argument. Make sure you have included this file as source if you run your GAPDoc documentation creating script. The second argument is a path to the directory where it can store the GAPDoc XML files. It will produce several files out of the Declare*WithDoc declarations you have used in your package package_name, and one named AutoDocMainFile.xml, which you can simply include to your documentation. section_intros is optional, it must be a list containing lists of of either two or three strings. If two are given, first one must be a chapter title, with underscores instead of spaces, and the second one a string which will be displayed in the documentation at the beginning of the chapter. If three are given, first one must be a chapter, second a section, third the description.

5.2 Global variable

5.2-1 AUTOMATIC_DOCUMENTATION
‣ AUTOMATIC_DOCUMENTATION( global variable )

This global variable stores all the streams and some additional data, like chapter names.

5.3 The declare functions

5.3-1 DeclareOperationWithDocumentation
‣ DeclareOperationWithDocumentation( name, list_of_filters, description, return_value[, arguments][, chapter_and_section][, option_record] )( function )

Returns: nothing

This method declares an operation, like DeclareOperation( name, list_of_filters ) would do. In addition, it specifies various information documenting the declared operation. They can be used to generate GAPDoc documentation files by calling CreateAutomaticDocumentation (5.1-1) in a suitable way.
The additional parameters have the following meaning:

description

This contains a descriptive text which is added to the generated documentation. It can either be a string or a list of strings. If it is a list of strings, then these strings are concatenated with a space between them.

return_value

A string displayed as description of the return value.

arguments

An optional string which is displayed in the documentation as arguments list of the operation.

chapter_and_section

An optional argument which, if present, must be a list of two strings, naming the chapter and the section in which the generated documentation for the operation should be placed. There are no spaces allowed in this string, underscores will be converted to spaces in the header of the chapter or the section.

option_record

option_record can be a record with some additional options. The following are currently supported:

group

This must be a string and is used to group functions with the same group name together in the documentation. Their description will be concatenated, chapter and section info of the first element in the group will be used.

function_label

This sets the label of the function to the string function_label. It might be useful for reference purposes, also this string is displayed as argument of this method in the manual. This really sets the label of the function, not the label of the ManItem. Please see the GAPDoc manual for more infos on labels and references.

5.3-2 DeclareCategoryWithDocumentation
‣ DeclareCategoryWithDocumentation( name, filter, description[, arguments][, chapter_and_section][, option_record] )( function )

Returns: nothing

This method declares a category, like DeclareCategory( name, filter ) would do.

The remaining parameters behave as described for DeclareOperationWithDocumentation (5.3-1).

5.3-3 DeclareRepresentationWithDocumentation
‣ DeclareRepresentationWithDocumentation( name, filter, list_of_req_entries, description[, arguments][, chapter_and_section][, option_record] )( function )

Returns: nothing

This method declares a representation, like DeclareRepresentation( name, filter, list_of_req_entries ) would do.

The remaining parameters behave as described for DeclareOperationWithDocumentation (5.3-1).

5.3-4 DeclareAttributeWithDocumentation
‣ DeclareAttributeWithDocumentation( name, filter, description, return_value[, argument][, chapter_and_section][, option_record] )( function )

Returns: nothing

This method declares an attribute, like DeclareAttribute( name, filter ) would do.

The remaining parameters behave as described for DeclareOperationWithDocumentation (5.3-1).

5.3-5 DeclarePropertyWithDocumentation
‣ DeclarePropertyWithDocumentation( name, filter, description[, arguments][, chapter_and_section][, option_record] )( function )

Returns: nothing

This method declares a property, like DeclareProperty( name, filter ) would do.

The remaining parameters behave as described for DeclareOperationWithDocumentation (5.3-1).

5.3-6 DeclareGlobalFunctionWithDocumentation
‣ DeclareGlobalFunctionWithDocumentation( name, description, return_value[, arguments][, chapter_and_section][, option_record] )( function )

Returns: nothing

This method declares a global function like DeclareGlobalFunction( name ) would do.

The remaining parameters behave as described for DeclareOperationWithDocumentation (5.3-1).

5.3-7 DeclareGlobalVariableWithDocumentation
‣ DeclareGlobalVariableWithDocumentation( name, description[, chapter_and_section] )( function )

Returns: nothing

This method declares a global variable like DeclareGlobalVariable( name ) would do.

The remaining parameters behave as described for DeclareOperationWithDocumentation (5.3-1).

5.3-8 DeclareOperationWithDoc
‣ DeclareOperationWithDoc( name, list_of_filters: description, return_value, arguments, chapter_info, label, function_label, group )( function )

Returns: nothing

This method declares an operation, like DeclareOperation( name, list_of_filters ) would do. In addition, it specifies various information documenting the declared operation. There can be used to generate GAPDoc documentation files by calling CreateAutomaticDocumentation (5.1-1) in a suitable way.
The remaining parameters are all optional and are passed via GAP's "function call with options" syntax. For example, you might write

    DeclareOperationWithDoc( "SomeOp", [IsInt] : description := "desc" )
    

in order to declare an operation with a certain description text. For details on the options syntax, see Reference: Function Call With Options. All of them are optional, a documentation entry will be created even if you specify none of them. The additional parameters have the following meaning:

description

This contains a descriptive text which is added to the generated documentation. It can either be a string or a list of strings. If it is a list of strings, then these strings are concatenated with a space between them.

return_value

A string displayed as description of the return value.

arguments

An optional string which is displayed in the documentation as arguments list of the operation.

chapter_info

An optional argument which, if present, must be a list of two strings, naming the chapter and the section in which the generated documentation for the operation should be placed. There are no spaces allowed in this string, underscores will be converted to spaces in the header of the chapter or the section.

group

This must be a string and is used to group functions with the same group name together in the documentation. Their description will be concatenated, chapter and section info of the first element in the group will be used.

function_label

This sets the label of the function to the string function_label. It might be useful for reference purposes, also this string is displayed as argument of this method in the manual. This really sets the label of the function, not the label of the ManItem. Please see the GAPDoc manual for more infos on labels and references.

5.3-9 DeclareCategoryWithDoc
‣ DeclareCategoryWithDoc( arg: description, arguments, chapter_info, label, function_label, group )( function )

Returns: nothing

This method declares a category, like DeclareCategory( arg ) would do.

The remaining options behave as described for DeclareOperationWithDoc (5.3-8).

5.3-10 DeclareRepresentationWithDoc
‣ DeclareRepresentationWithDoc( arg: description, arguments, chapter_info, label, function_label, group )( function )

Returns: nothing

This method declares a representation, like DeclareRepresentation( arg ) would do.

The remaining options behave as described for DeclareOperationWithDoc (5.3-8).

5.3-11 DeclareAttributeWithDoc
‣ DeclareAttributeWithDoc( arg: description, return_value, argument, chapter_info, label, function_label, group )( function )

Returns: nothing

This method declares an attribute, like DeclareAttribute( arg ) would do.

The remaining options behave as described for DeclareOperationWithDoc (5.3-8).

5.3-12 DeclarePropertyWithDoc
‣ DeclarePropertyWithDoc( arg: description, arguments, chapter_info, label, function_label, group )( function )

Returns: nothing

This method declares a property, like DeclareProperty( arg ) would do.

The remaining parameters behave as described for DeclareOperationWithDoc (5.3-8).

5.3-13 DeclareGlobalFunctionWithDoc
‣ DeclareGlobalFunctionWithDoc( arg: description, return_value, arguments, chapter_info, label, function_label, group )( function )

Returns: nothing

This method declares a global function like DeclareGlobalFunction( arg ) would do.

The remaining parameters behave as described for DeclareOperationWithDoc (5.3-8).

5.3-14 DeclareGlobalVariableWithDoc
‣ DeclareGlobalVariableWithDoc( arg: description, chapter_info, label, function_label, group )( function )

Returns: nothing

This method declares a global variable like DeclareGlobalVariable( arg ) would do.

The remaining parameters behave as described for DeclareOperationWithDoc (5.3-8).

5.4 The install functions

5.4-1 InstallMethodWithDocumentation
‣ InstallMethodWithDocumentation( name, short_descr, list_of_filters, description, return_value[, arguments][, chapter_and_section], func )( function )

Returns: nothing

This method installs a method, like InstallMethod( name, short_descr, list_of_filters, func ) would do.

The remaining parameters behave as described for DeclareOperationWithDocumentation (5.3-1).

5.4-2 InstallMethodWithDoc
‣ InstallMethodWithDoc( arg: description, return_value, arguments, chapter_info, label, function_label, group )( function )

Returns: nothing

This method installs a method, like InstallMethod( arg ) would do.

The remaining parameters behave as described for DeclareOperationWithDoc (5.3-8).

5.5 The create functions

5.5-1 CreateDocEntryForCategory
‣ CreateDocEntryForCategory( name, filter, description[, arguments][, chapter_and_section][, option_record] )( function )

Returns: nothing

This works like DeclareCategoryWithDocumentation (5.3-2) except that it does not call DeclareCategory.

5.5-2 CreateDocEntryForRepresentation
‣ CreateDocEntryForRepresentation( name, filter, list_of_req_entries, description[, arguments][, chapter_and_section][, option_record] )( function )

Returns: nothing

This works like DeclareRepresentationWithDocumentation (5.3-3) except that it does not call DeclareRepresentation.

5.5-3 CreateDocEntryForOperation
‣ CreateDocEntryForOperation( name, list_of_filters, description, return_value[, arguments][, chapter_and_section][, option_record] )( function )

Returns: nothing

This works like DeclareOperationWithDocumentation (5.3-1) except that it does not call DeclareOperation.

5.5-4 CreateDocEntryForAttribute
‣ CreateDocEntryForAttribute( name, filter, description, return_value[, argument][, chapter_and_section][, option_record] )( function )

Returns: nothing

This works like DeclareAttributeWithDocumentation (5.3-4) except that it does not call DeclareAttribute.

5.5-5 CreateDocEntryForProperty
‣ CreateDocEntryForProperty( name, filter, description[, arguments][, chapter_and_section][, option_record] )( function )

Returns: nothing

This works like DeclarePropertyWithDocumentation (5.3-5) except that it does not call DeclareProperty.

5.5-6 CreateDocEntryForCategory_WithOptions
‣ CreateDocEntryForCategory_WithOptions( arg: description, chapter_info, label, function_label, group )( function )
‣ CreateDocEntryForRepresentation_WithOptions( arg: description, chapter_info, label, function_label, group )( function )
‣ CreateDocEntryForProperty_WithOptions( arg: description, chapter_info, label, function_label, group )( function )
‣ CreateDocEntryForAttribute_WithOptions( arg: description, chapter_info, label, function_label, group )( function )
‣ CreateDocEntryForOperation_WithOptions( arg: description, chapter_info, label, function_label, group )( function )
‣ CreateDocEntryForGlobalFunction_WithOptions( arg: description, chapter_info, label, function_label, group )( function )
‣ CreateDocEntryForGlobalVariable_WithDoc( arg: description, chapter_info, label, function_label, group )( function )

Returns: nothing

Does the same as Declare*WithDoc but without declaring anything.

5.6 Additional functions

5.6-1 SetCurrentAutoDocChapter
‣ SetCurrentAutoDocChapter( name )( function )
‣ ResetCurrentAutoDocChapter( )( function )
‣ SetCurrentAutoDocSection( name )( function )
‣ ResetCurrentAutoDocSection( )( function )

These functions set or reset a current chapter or section, which will be applied to entries without a chapter_info instead of the default one. Note that setting a section without a chapter does nothing, and reseting the chapter also resets the section.

5.6-2 WriteStringIntoDoc
‣ WriteStringIntoDoc( description: chapter_info )( function )

Writes a string or a list of strings given as argument description into doc. chapter_info is optional, but without a current chapter set, this would cause an error. Also it is possible here to only give the chapter, not the section. It will be written in the chapter at the current point, i.e. after the last written section.

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

generated by GAPDoc2HTML