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:
© Copyright 2009-2024 James Watts. All rights reserved.

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
  2. Schema Definition
  3. Elements Reference
  4. Supported Languages

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

attrs

Contains the attributes of the tag.

Allowed elements: attr


<attrs> ... </attrs>

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:



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