apidoc

The "apidoc" element allows to embed an internal API for any language. It does not refer to an existing API structure, but it shows the API in the document. The APIs provided by default are:

• "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

It is possible to add any other language API and to configure them by specifying the API documentation configuration.

Limitation

For the moment, this kind of element is not rendered in PDF or DOCX.

Structure

The apidoc element contains element children. Any element can also have other element children.

apidoc

The apidoc element has the following attributes:

• "lang": the API (for example "java")^[2]
  The default APIs are "java", "csharp", "python," and "doxygen"
  . See API documentation configuration for more information
• "type": the type of the element (for example "class"). It must be a valid top-level element for the API specified by "lang"
• "path": the path of the element (for example "JButton")
• "modifiers": the optional modifiers of the element (for example "public void")

The text content of this element will be ued to add the textual specificaiton of this element. It can use a lot of the wiki syntax, including references.

For example, for a Java class, we could have:

   <apidoc lang="java" type="class" path="JButton" modifiers="public">An implementation of a "push" button.
   ...

This element contains element children.

element

The element element has the following attributes:

• "type": the type of the element (for example "method"). It must be a valid element for the API specified by "lang"
• "path": the path of the element (for example "supportedElements()")
• "modifiers": the optional modifiers of the element (for example "public int")

For example, for a Java method: we could have:

     <element type="method" path="setDefaultCapable(int defaultCapable)">Sets the defaultCapable property, which determines whether this button
  can be made the default button for its root pane.element</element>

This element can contain other element children.

Examples

Java examples

A Java class:

  <apidoc lang="java" type="class" path="JButton" modifiers="public">An implementation of a "push" button.
     <element type="method" path="AccessibleContext getAccessibleContext()">Gets the AccessibleContext associated with this JButton</element>      
     <element type="method" path="setDefaultCapable(boolean defaultCapable)">Sets the defaultCapable property, which determines whether this button
  can be made the default button for its root pane.
        <element type="argument" path="defaultCapable">The defaultCapable value</element>
     </element>
     <element type="method" path="setDefaultCapable(int defaultCapable)">Sets the defaultCapable property, which determines whether this button
  can be made the default button for its root pane.element</element>
     <element type="method" modifiers="public" path="Set<String> supportedElements()">Handle an element</element>
  </apidoc>

The result is:

public class JButton

An implementation of a "push" button.

Method Summary

Modifier and Type	Method and Description
AccessibleContext	getAccessibleContext() Gets the AccessibleContext associated with this JButton
void	setDefaultCapable(boolean defaultCapable) Sets the defaultCapable property, which determines whether this button can be made the default button for its root pane. Parameters defaultCapable - The defaultCapable value
void	setDefaultCapable(int defaultCapable) Sets the defaultCapable property, which determines whether this button can be made the default button for its root pane.element
Set<String>	supportedElements() Handle an element

Python example

A Python module:

  <apidoc lang="python" type="module" path="Class">Representation of a class documentation
     <element type="field" path="doc">A mapping from identifier name to a Doc objects</element>
     <element type="method" path="class_variables(self, include_inherited=True, sort=True)">
  Returns an optionaly-sorted list of Variable objects that represent this class class variables.</element>
  </apidoc>

The result is:

module Class

Representation of a class documentation

def	doc A mapping from identifier name to a Doc objects

def	class_variables(self, include_inherited=True, sort=True) Returns an optionaly-sorted list of Variable objects that represent this class class variables.

CSharp examples

A C# class

  <apidoc lang="csharp" type="class" path="Console">Representation of the Console class
     <element type="property" path="BackgroundColor">Gets or sets the background color of the console.</element>
     <element type="property" path="BufferHeight">Gets or sets the height of the buffer area.</element>
     <element type="method" path="beep()">Plays the sound of a beep of a specified frequency and duration 
  through the console speaker.</element>
  </apidoc>

The result is:

Class Console

Representation of the Console class

Properties

BackgroundColor	Gets or sets the background color of the console.
BufferHeight	Gets or sets the height of the buffer area.

Methods

beep()	Plays the sound of a beep of a specified frequency and duration through the console speaker.

A C# enum

  <apidoc lang="csharp" type="enum" path="DateTimeKind">Specifies whether a DateTime object represents a local time, a Coordinated Universal Time (UTC), 
  or is not specified as either local time or UTC.
     <element type="constant" path="Local">The time represented is local time.</element>      
     <element type="constant" path="Utc">The time represented is local Utc.</element>            
  </apidoc>

The result is:

Enum DateTimeKind

Specifies whether a DateTime object represents a local time, a Coordinated Universal Time (UTC), or is not specified as either local time or UTC.

Fields

Local	The time represented is local time.
Utc	The time represented is local Utc.

Doxygen examples

A C++ class

  <apidoc lang="doxygen" type="class" path="XMLAttr">This class defines the information about an attribute that will 
  come out of the scanner during parsing.
     <element type="constructor" path="XMLAttr(MemoryManager *const manager=XMLPlatformUtils::fgMemoryManager)">The default constructor 
  just setsup an empty attribute to be filled in the later.</element>
     <element type="destructor" path="~XMLAttr()"></element>
     <element modifiers="int" type="method" path="toCompare (const XMLBigDecimal &other)">Compares this object to the specified object </element>
  </apidoc>

The result is:

XMLAttr class Reference

This class defines the information about an attribute that will come out of the scanner during parsing.

Methods

toCompare (const XMLBigDecimal &other)	Compares this object to the specified object

A C header

  <apidoc lang="doxygen" type="header" path="uset.h">This is a C wrapper around the C++ UnicodeSet class.
     <element type="struct" path="USerializedSet">A serialized form of a Unicode set.</element>
     <element type="macro" path="U_UNICODE_VERSION">Unicode version number, default for the current ICU version.</element>
     <element type="macro" path="UCHAR_MAX_VALUE">The highest Unicode code point value (scalar value) according to The Unicode Standard.</element>
     <element type="typedef" path="USet">USet is the C API type corresponding to C++ class UnicodeSet.</element>
     <element type="typedef" path="USerializedSet">A serialized form of a Unicode set.</element>
     <element type="enum" path="USetSpanCondition">Argument values for whether span() and similar functions 
  continue while the current character is contained.
        <element type="constant" path="USET_SPAN_NOT_CONTAINED">Continues a span() while there is no set element
  at the current position</element>      
        <element type="constant" path="USET_SPAN_CONTAINED">Spans the longest substring that is a concatenation 
  of set elements (characters or strings)</element>           
     </element>
     <element modifiers="USet*" type="function" path="uset_openEmpty (void)">Create an empty USet object.</element>
     <element modifiers="USet*" type="function" path="uset_open (UChar32 start, UChar32 end)">Creates a USet object that contains the range 
  of characters start..end, inclusive</element>
  </apidoc>

The result is:

uset.h header Reference

This is a C wrapper around the C++ UnicodeSet class.

Macros

UCHAR_MAX_VALUE	The highest Unicode code point value (scalar value) according to The Unicode Standard.
U_UNICODE_VERSION	Unicode version number, default for the current ICU version.

Enumerations

enum {USET_SPAN_CONTAINED, USET_SPAN_NOT_CONTAINED} Argument values for whether span() and similar functions continue while the current character is contained.

Data Structures

Data Structures	Struct Reference
USerializedSet	A serialized form of a Unicode set.

Typedefs

USerializedSet	A serialized form of a Unicode set.
USet	USet is the C API type corresponding to C++ class UnicodeSet.

Functions

uset_openEmpty (void)	Create an empty USet object.
uset_open (UChar32 start, UChar32 end)	Creates a USet object that contains the range of characters start..end, inclusive

A C enum

 <apidoc lang="doxygen" type="enum" path="USetSpanCondition">Argument values for whether span() and similar functions 
 continue while the current character is contained.
    <element type="constant" path="USET_SPAN_NOT_CONTAINED">Continues a span() while there is no set element
 at the current position</element>      
    <element type="constant" path="USET_SPAN_CONTAINED">Spans the longest substring that is a concatenation 
 of set elements (characters or strings)</element>  
 </apidoc>

The result is:

USetSpanCondition enum Reference

Argument values for whether span() and similar functions continue while the current character is contained.

Enum Constant Summary

USET_SPAN_CONTAINED	Spans the longest substring that is a concatenation of set elements (characters or strings)
USET_SPAN_NOT_CONTAINED	Continues a span() while there is no set element at the current position

A C struct

 <apidoc lang="doxygen" type="struct" path="USerializedSet">A serialized form of a Unicode set
    <element type="field" path="array">The serialized Unicode Set</element>
    <element type="field" path="bmpLength">The length of the array that contains BMP characters</element>
 </apidoc>

The result is:

USerializedSet Struct Reference Reference

A serialized form of a Unicode set

Field Documentation

array	The serialized Unicode Set
bmpLength	The length of the array that contains BMP characters