APIDoc DokuWiki Plugin

The APIDoc is a DokuWiki plugin for easy documentation of API:s.

The current version of the plugin is 1.1, and it can be downloaded here.

The DokuWiki plugins page can be found here.

Installation

The plugin is installed by simply unpacking the tar.gzip archive in the lib/plugins directory under the wordpress install path.

Contents

The archive contains two files: syntax.php and style.css. The .php-file contains the functionallity for the plugin while the .css file has all the associated CSS style sheets. In the future the parsing functionallity will be separated from the DokuWiki plugin code and added to a separate file to be able to re-use the code for a WordPress plugin.

Usage

When the plugin is installed it will replace everything that’s contained within a apidoc tag with the parsed data.

<apidoc> </apidoc>

The syntax of the parsed data is a keyword, followed by a set of parameters separated by the | character.

The following keywords and parameters are currently supported, observe that all parameters need to be set and the line is ended with a | character:

  • CLASS
    • ClassName
    • FileName
    • Extends
    • Description
  • FIELD
    • FieldName
    • Definition
    • Description
  • METHOD
    • MethodName
    • Definition
    • Returns
    • Description
  • PARAMETER
    • ParameterName
    • ParameterType
    • Default value
    • Description

Keywords and parameters, description

Keyword: CLASS
The CLASS keyword has to be the first keyword defined in the data and there can only be one CLASS keyword in the data set. This keyword describes the class that is documented in this apidoc element.

Parameter: CLASS.ClassName
The ClassName is the name of the class documented in this apidoc element.

Parameter: CLASS.FileName
The path and name of the file where this class is implemented.

Parameter: CLASS.Extends
A list of classes and interfaces that this class extends or implements.

Parameter: CLASS.Description
Elaborate description of this class.

Example:

<apidoc>
CLASS|MyClass|/tmp/myclass.php||Just a test class for documentation purposes.|
</apidoc>

Keyword: FIELD
The FIELD keyword is used to document public variables and constants in the documented class.

Parameter: FIELD.FieldName
The name of the variable or constant documented.

Parameter: FIELD.Definition
A snippet of code describing how this variable/constant is defined in the source code, with values if applicable.

Parameter: FIELD.Description
Elaborate description of this field.

Example:

<apidoc>
CLASS|MyClass|/tmp/myclass.php||Just a test class for documentation purposes.|
FIELD|$myField|public const $myField = 0x001;|Just a constant assigned to this class|
</apidoc>

Keyword: METHOD
The METHOD keyword is used to document a public method in the documented class.

Parameter: METHOD.MethodName
The name of the method documented.

Parameter: METHOD.Definition
A snippet of code describing how this method is defined in the source code, with return types and parameters.

Parameter: METHOD.Returns
Type and description of returned data.

Parameter: METHOD.Description
Elaborate description of the documented method.

Example:

<apidoc>
CLASS|MyClass|/tmp/myclass.php||Just a test class for documentation purposes.|
METHOD|myMethod|public function myMethod( $test )|String - The text "Hello World"|This is just a test method that will always return a static string.|
</apidoc>

Keyword: PARAMETER
The PARAMETER keyword is used to document a parameter associated with a method. This keyword needs to be superceded by a METHOD keyword or an error will be raised. All parameters will be associated with the last previously defined method.

Parameter: PARAMETER.ParameterName
The name of the parameter specified.

Parameter: PARAMETER.ParameterType
The data type of the parameter specified.

Parameter: PARAMETER.Default value
If the parameter has a default value, put it here.

Parameter: PARAMETER.Description
Elaborate description of the documented parameter.

Example:

<apidoc>
CLASS|MyClass|/tmp/myclass.php||Just a test class for documentation purposes.|
METHOD|myMethod|public function myMethod( $test )|String - The text "Hello World"|This is just a test method that will always return a static string.|
PARAMETER|$test|boolean|false|Just for testing, true or false
</apidoc>

 

Parsing and processing

All documented source code will be syntax-highlighted and associated stylesheets are found in the .css file of the plugin.

Since the | character is reserved to separate fields in the data, links to other pages are on the format [[URL/Text]] instead of the default [[URL|Text]].

Suggestions, questions, comments?

If you have any input regarding this module, please send us an email and we’ll get back to you as soon as possible.

Changelog

  • [2015-11-12] Version 1.1: Added [[]] link parsing and implemented better keyword parsing, now keywords can be left out
  • [2015-11-10] Version 1.0: Initial APIDoc version released

ToDo

  • Throws parameter for METHOD keyword
  • Fix bug regarding ”