DDD Annotations

DDD annotations can be placed in source code comments and wiki documents.

Syntax

The format is:

 ~TYPE FIELDS* MESSAGE*~
TYPE The type of annotation. FIELDS An optional list of key:value pairs. A colon separates the key and value. MESSAGE Optional content of the annotation.
  • DDD annotations are placed between tildes. The first tilde must be the first character on a line.
  • Field keys and values must use quotes if they contain spaces or escaped quotes.
  • Message cannot contain the tilde character.

Fields and content syntax are specific to each annotation type.

Examples

A task with 3 fields.

 ~task status:inprogress priority:high description:"Fix spelling" ~

A task with 2 fields, and content.

 ~task status:inprogress priority:high Fix spelling ~

Using whitespace.

 ~task 
    status : inprogress 
    priority : high 
    Fix spelling ~

Implied fields. For example, the task annotation can extract fields from the content).

 ~task in-progress 50% spellcheck this document~

JSON Format

When represented as JSON, the structure is:

[
    {
        "type":"feature",
        "fields":{"priority":"low","release":"next"},
        "message":"Add a spellcheck option to the editor."
    },
    {
        "type":"bug",
        "fields":{"priority":"high","release":"current"},
        "message":"Smoke comes out of the server."
    }
]

Standard Tags and Annotations

How to markup docs with:

  • unreviewed
  • incomplete
  • placeholders
  • replaceable text
  • linked info
  • new features
  • feature release
  • bug fixes

Issue Management (task|bug|feature|todo)

Specifies issues related to software improvement.

Optional fields

  • completed status
  • queue status
  • category
  • target release

If the annotation does not contain a caption, the preceding line is used as the caption. If the caption is 'document or implement, the preceding line is appended to the caption.

Documentation Type (type)

Specifies the type of documentation. This annotation is active until replaced with another declaration. Multiple documentation types can be specified.

Symbol Type
u User
d Developer
i Implementor
p Purchaser
a Acquirer

You can use the full or partial name instead of a single letter.

 ~type u ~
user doc here...

 ~type developer ~
developer doc here...

 ~type u i~
implementer and user doc here...