Internal API documentation configuration

The "apidocs" property in the configuration file or the command-line specifies a custom internal API documentations. It specifies the structure of any language API which can be used in the apidoc syntax element.

Note that contrary to the APIs property configuration, the API will be included in the wiki.

Overview

The "apidocs" configuration file is an XML file which defines an API structure for programming languages.For each language, the API defines:

• The list of elements which can be used at the root level of the API in the wiki (for example, it can be a class or an interface for a Java API
• The list of elements managed in the API, and for each element, its possible children elements, and the order in which they should be presented in the wiki. For example, the class element in a Java API can have it this order: property, field, constructor, an method children

Default APIs

Several APIs are provided by default:

• "java": The Java API, similar to the API generated by the javadoc tool
• "python": The Python API, similar to the pdoc-generated API "pdoc-like" API for a Python class^[1]
  See pdoc3.github.io
• "csharp": The C# API, similar to the one generated by Visual Studio
• "doxygen": The Doxygen API, allowing to be used with a C or C++ API

Default APIs and generic APIs

Note that you must make a difference between the default APIs and the Generic APIs types:

• The generic APIs types are the types of language models, associated with default styles to generate the API, that you can use
• The default APIs are just some APIs build on these generic API types, which are always available

It can be difficult to understand the difference, because each default API ahs the same name as the generic API is uses for its language model. For example, for the default "java" API:

   <api id="java" desc="Java" type="java">

Defining your own APIs

You can define your own APIs by specifying an "apiDocs" XML file for the "apidocs" property on the command-line or the configuration file.

These APIs will be added to the ones provided by default. Beware that you can't override the default APIs definitions by your own. For example, if you want to specify your own Java API, you can't specify something like:

  <api id="java" desc="Java" type="java">
  ...

but you can specify:

   <api id="java2" desc="Java" type="java">
   ...

Structure

The API documentation configuration Schema is the schema for the XML configuration file.

Top-level element

The top-level element for the XML file iself it the APIDocs element. The children of this element are api elements, each of these elements specifying one language API. For example:

   <APIDocs version="1.0">
      <api id="mylanguage" desc="Java" type="java">
   ...
      </api>
      <api id="mySecondlanguage" desc="Python" type="python">
   ...
      </api>         
   </APIDocs>

api

The api is the specification for one language API. This element has the following attributes:

• "desc": informative, gives a more human-readable name for the API
• "id": identifier of the API
• "type": the type of the API. This attribute must have one of the following values: "java", "python", "csharp", "doxygen". See also API type

Each api has only element children.

For example:

   <api id="java" desc="Java" type="java">
   ..

API type

The API type represents the generic type of the API to use for your API. Elements which are not managed by this generic API type won't be rendered by your own API^[2]

For example, "event" elements will not appear in your "apidoc" element if you use the java generic API type

. See list of managed elements for more information.

The generic API type is also used to show in the wiki an API similar to the API generated for each of these languages:

• "java" will show a javadoc-like API. See Java generic API
• "csharp" will show a csharp-like API. See CSharp generic API
• "python" will show a pydoc-like API. See Python generic API
• "doxygen" will show a doxygen-like API. See Doxygen generic API

element

An element is the specification for one element used in an API^[3]

for example method or class elements

. It has the following attributes:

• "type": the type of the element, can br one of the types defined in Generic API types
• "name": name of the element. Contrary to hte type, it is specific to the api and you can use any name you want
• "topElement": if set to true, indicates that this element can be a top-element in the api

An element has the following children:

• "children": a unique XML element which specifies the ordered list of children elements allowed under this element. The "children" element contains only child elements
• "property": allows to specify properties for this element in the API
• "style": allows to specify custom CSS styles for this element in the API html rendering

child

A child is an element which is allowed under another parent element. The order of children is significant (it is the order in which the children will be presented in the wiki).

A child has the following attributes:

• "name": the name of the element. It must corespond to an element specified for the associated parent api
• "title": optional, represents the title of the table which will present the elements of this type under their parent element. If this attribute is not present, no title will be shown

For example here the class element can have the following children: property, field, constructor, and method:

      <element type="class" name="class" topElement="true">
         <children>
            <child name="property" title="Property Summary" />  
            <child name="field"  title="Fields" /> 
            <child name="constructor" title="Constructor Summary" />             
            <child name="method" title="Method Summary" />         
         </children>       
      </element>

property

Properties are usually used to give specific names to the table outputs. There are four types of properties:

• "modifierAndType": the property ID for method elements return type and visibility, and all the elements for which the parent type is method
• "description": the property ID for method elements description, and all the elements for which the parent type is method
• "params": the property ID for argument elements description
• "constants": the property ID for constant elements values description

Note: see Generic API types for the list of parent types).

The following example presents the properties declaration for the "java" api:

   <element type="method" name="method">
      <children>
         <child name="argument" />       
      </children>           
      <property id="modifierAndType" desc="Modifier and Type" />
      <property id="description" desc="Method and Description" />
      <property id="params" desc="Parameters" /> 
   </element>

style

It is possible to specify custom CSS styles for an element in the html rendering. It will override the styles defined for this element by default in the API type.

Example

The following example shows the specification of the java API:

   <api id="java" desc="Java" type="java">
      <element type="class" name="class" topElement="true">
         <children>
            <child name="property" title="Property Summary" />  
            <child name="field"  title="Fields" /> 
            <child name="constructor" title="Constructor Summary" />             
            <child name="method" title="Method Summary" />           
         </children>       
      </element>
      <element type="interface" name="interface" topElement="true">
         <children>          
            <child name="method" title="Method Summary" />         
         </children>       
      </element>      
      <element type="field" name="field">
         <property id="modifierAndType" desc="Modifier and Type" />
         <property id="description" desc="Field and Description" />
      </element>   
      <element type="enum" name="enum" topElement="true">
         <children>
            <child name="constant" title="Enum Constant Summary" />  
            <child name="method" title="Method Summary" />         
         </children>             
         <property id="constants" desc="Enum Constants" />      
      </element>  
      <element type="property" name="property">       
         <property id="modifierAndType" desc="Type" />
         <property id="description" desc="Property and Description" />
      </element>   
      <element type="constant" name="constant"/>    
      <element type="method" name="method">
         <children>
            <child name="argument" />       
         </children>           
         <property id="modifierAndType" desc="Modifier and Type" />
         <property id="description" desc="Method and Description" />
         <property id="params" desc="Parameters" /> 
      </element> 
      <element type="constructor" name="constructor">
         <children>
            <child name="argument" />       
         </children>           
         <property id="description" desc="Constructor and Description" />
         <property id="params" desc="Parameters" /> 
      </element>       
      <element type="argument" name="argument" />  
   </api>