DocML Specification 1.0
Namespace Document 1 June 2010
- This version:
- http://www.docml.org/spec (xsd)
- Latest version:
- http://www.docml.org/spec (xsd)
- Author:
This work is licensed under a Creative Commons Attribution License. This copyright applies to the DocML Specification and accompanying documentation. Regarding underlying technology, DocML uses the W3C's XML technology, an open Web standard that can be freely used by anyone.
Abstract
This specification describes the DocML language, defined as a collection of named elements and attributes using the W3C's XML technology.
Status of this Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document.
This is the first version of the DocML specification. It is produced as an authoritative documentation of the status and use of the Documentation Markup Language, also known as "DocML".
The language is extensible, meaning that you may extend the predefined elements and attrbiutes with additional definitions. However, it is encouraged that modifications that can be considered "useful" for others or "important additions" to the language be proposed to the author for incorporation in the next revision of the specification.
See the changes section for details of the changes in this version of the specification.
Table of Contents
1. Introduction
Currently, the most common means of documenting source code is the addtion of comments within the code itself. These comments are typically labelled with symbols and/or keywords to delimit aspects of the documentation, for example, @author. Some argue that the most obvious place for documentation of source code is in the context of the code itself, however, a developer rarely needs or wants to view the source code of a program in order to understand how an aspect of that program works.
Tools such as JavaDoc solve this problem by extracting the comments from the source code and presenting them in a browser interface. This is a handy tool, but the documentation for the code remains mixed in with the code. What about translations of the documentation? Do we duplicate the source code and translate the comments? What about versons of the documentation which don't necesarily reflect changes in the source code, just in the documentation itself? Do we duplicate the source code and just change the comments? And what about people who want to interact with the documentation without touching the source files? How do we distribute the documentation to third parties without distributing the source code itself? How can we semantically represent elements of the documentation that allows anyone to easily format the documentation in a way that suits them best?
The Documentation Markup Language aims to solve these problems by providing a standard method for documentation which allows for greater protability, manipulation and presentation. By using the W3C's XML technology the documentation is stored in a platform independent format which is well-structured, machine-readable and easy to modify. The semantic aspect of XML also makes it simple to navigate and read in its raw format.
The main advantage of using DocML over traditional comments within the code is the opportunity it offers to create rich applications and graphical interfaces to both consume and edit documentation. Furthermore, the extensible nature of DocML makes it easily adaptable to new programming languages, or even the documentation of topics other than source code for programs.
2. Schema Definition
The schema definition for the Documentation Markup Language can be downloaded from here.
3. Elements Reference
Here you can find a reference of all the elements and their attributes defined in the Documentation Markup Language.
docml
Root node for DocML documents.
| Attribute | Description |
|---|---|
| name required | The name of the project. |
| desc | A description of the project. |
| version | The current version of the project. |
| build | The build date/reference of the project. |
| code required | The programming language of the documented code. |
| author | The author(s) of the documentation. |
| lang | The language of the text in the documentation. |
| license | The distribution license for the documentation. |
| copyright | The copyright of the documentation. |
| link | A URL to the project website or code repository. |
Allowed elements: group, ns, interface, class, obj, array, hash, fn, var, const, notes
<docml name="project" version="1.0" code="php"> ... </docml>
group
Delimits a group of elements. This is mainly used to create sections in documentation. Creating a group has no semantic value over the contained elements other than to suggest they are related.
| Attribute | Description |
|---|---|
| name required | The name of the namespace. |
| desc | A description of the namespace. |
Allowed elements: group, ns, interface, class, obj, array, hash, fn, var, const, notes
<group name="something"> ... </group>
ns
Represents a namespace within the program. Can be used to simply imply a namespace, or can contain child elements, which explicitly suggests that those elements are within that namespace.
| Attribute | Description |
|---|---|
| name required | The name of the namespace. |
| desc | A description of the namespace. |
| tags | Coma separated list of tags. |
Allowed elements: group, ns, interface, class, obj, array, hash, fn, var, const, notes
<ns name="something" /> or <ns name="something"> ... </ns>
interface
Represents an interface in the program, not to be confused with a graphical interface.
| Attribute | Description |
|---|---|
| name required | The name of the interface. |
| extends | Name of a class the interface extends. |
| implements | Name of an interface the interface implements. |
| desc | A description of the interface. |
| tags | Coma separated list of tags. |
Allowed elements: obj, array, hash, fn, prop, src, code, args, notes
<interface name="something"> ... </interface>
class
Represents a class in the program. Should not be used to represent a virtual object, use obj instead.
| Attribute | Description |
|---|---|
| name required | The name of the class. |
| abstract | "true" in the class is abstract. |
| extends | Name of a class the class extends. |
| implements | Name of an interface the class implements. |
| desc | A description of the class. |
| tags | Coma separated list of tags. |
Allowed elements: obj, array, hash, fn, prop, src, code, args, notes
<class name="something"> ... </class>
obj
Represents an object in the program. Can be an instance of a class or a virtual object.
| Attribute | Description |
|---|---|
| name required | The name of the object. |
| instanceof | The name of the instantiating class. |
| desc | A description of the object. |
| tags | Coma separated list of tags. |
Allowed elements: obj, array, hash, fn, prop, src, code, notes
<obj name="something"> ... </obj>
array
Represents an array in the program. Arrays with keys should be represented as a hash table.
| Attribute | Description |
|---|---|
| name required | The name of the array. |
| desc | A description of the array. |
| tags | Coma separated list of tags. |
Allowed elements: item
<array name="something"> ... </array>
hash
Represents a hash table in the program.
| Attribute | Description |
|---|---|
| name required | The name of the hash table. |
| desc | A description of the hash table. |
| tags | Coma separated list of tags. |
Allowed elements: item
<hash name="something"> ... </hash>
fn
Represents a function or method in the program. A function is considered a method when it is defined within an interface, a class or an object.
| Attribute | Description |
|---|---|
| name required | The name of the function or method. |
| construct | "true" if the function is a constructor. |
| final | "true" if the method is final. |
| static | "true" if the method is static. |
| scope | The scope of the method (public, protected or private). |
| desc | A description of the function or method. |
| tags | Coma separated list of tags. |
Allowed elements: return, src, code, args, notes
<fn name="something"> ... </fn>
tag
Represents a markup tag in the program.
| Attribute | Description |
|---|---|
| name required | The name of the tag. |
| ns | The namespace of the markup. |
| desc | A description of the tag. |
| tags | Coma separated list of tags. |
Allowed elements: code, attrs, notes
<tag name="something"> ... </tag>
prop
Represents a property of an interface, a class or an object.
| Attribute | Description |
|---|---|
| name required | The name of the property. |
| value | The value of the property. |
| type | The data type of the value. |
| final | "true" if the property is final. |
| static | "true" if the property is static. |
| scope | The scope of the property (public, protected or private). |
| desc | A description of the property. |
| tags | Coma separated list of tags. |
Allowed elements: none
<prop name="something" value="hello world" />
var
Represents a variable in the program.
| Attribute | Description |
|---|---|
| name required | The name of the variable. |
| value | The value of the variable. |
| type | The data type of the value. |
| desc | A description of the variable. |
| tags | Coma separated list of tags. |
Allowed elements: none
<var name="something" value="hello world" />
const
Represents a constant in the program.
| Attribute | Description |
|---|---|
| name required | The name of the constant. |
| value | The value of the constant. |
| type | The data type of the value. |
| desc | A description of the constant. |
| tags | Coma separated list of tags. |
Allowed elements: none
<const name="something" value="hello world" />
item
Defines an item of a hash table or an array.
| Attribute | Description |
|---|---|
| index | The numeric index of the item if an array. |
| key | The key value of the item if a hash table. |
| desc | A description of the item. |
Allowed elements: obj, array, hash, fn, prop, var
<item key="something"> ... </item>
return
Represents the return value of a function in the program. Multiple return values are represented as multiple return nodes.
| Attribute | Description |
|---|---|
| type | The data type of the return value. |
| desc | A description of the return value. |
Allowed elements: obj, array, hash, fn, var
<return type="object"> ... </return>
code
Provides a usage example of the element.
Allowed elements: none
<code><![CDATA[ ... ]]></code>
src
Provides the source code of the element.
Allowed elements: none
<src><![CDATA[ ... ]]></src>
args
Contains the input arguments.
| Attribute | Description |
|---|---|
| as | Can be arguments, object, hash or array. |
Allowed elements: arg
<args as="arguments"> ... </args>
arg
Defines an input argument.
| Attribute | Description |
|---|---|
| name required | The name of the argument, the object property, the hash key or the index of the array. |
| type required | The data type of the value. |
| def | The default value of the argument. |
| req | "true" if the argument is required. |
| desc | A description of the argument. |
Allowed elements: none
<arg name="something" type="boolean" />
attr
Defines an attribute.
| Attribute | Description |
|---|---|
| name required | The name of the attribute. |
| type required | The data type of the value. |
| def | The default value of the attribute. |
| req | "true" if the attribute is required. |
| desc | A description of the attribute. |
Allowed elements: none
<attr name="something" />
notes
Contains additional notes about an element of the program.
Allowed elements: note
<notes> ... </notes>
note
Defines a note.
Allowed elements: none
<note author="James Watts"> ... </note>
4. Supported Languages
As of the version DocML supports the following programming languages:
- C/C++
- Java
- .NET
- PHP
- Python
- Perl
- JavaScript
- ActionScript
- VBScript
- C#
- HTML
- XML
- XUL
- MetaBasic
Acknowledgments
It is worth mentioning that the Documentation Markup Language was designed and created using open source software, namely Linux (Fedora), SciTE and Mozilla Firefox.
Changes
- Current version reflects no changes
