[Boost-docs] Quickbook blocks for concepts

Subject: [Boost-docs] Quickbook blocks for concepts
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2010-02-07 18:42:20

Hi,

I'm documenting Boost.Geometry in Quickbook and spending a lot of time
browsing through existing Bodost ocumentations and figuring out
how to properly structure documentation of concepts. It is not easy task.

There are some predefined blocks in Quickbook, like variablelist.
I'm wondering if it would be beneficial to define a block dedicated
for documenting concepts. Roughly, I've been thinking of something
along these lines:

[concept MyConcept [my concept description]

  [notation
    [term 1] [description 1]
    [term 2] [description 2]
  ]

  [refinement [concept 1] [concept 2]]

  [associated
    [type 1] [description 1]
    [type 2] [description 2]
  ]

  [expressions
    [name 1 [expr 1] [type requirement 1] [return type 1]
    [name 2 [expr 2] [type requirement 2] [return type 2]
  ]

  [semantics
    [name 1 [expr 1] [precondition 1] [semantic 1] [postcondition 1]
    [name 2 [expr 2] [precondition 2] [semantic 2] [postcondition 2]
  ]

  [complexity [...]]

  [invariants
    [invariant 1] [description 1]
    [invariant 2] [description 2]
  ]

  [models [model 1] [model 2]]

  [notes
    [ note 1]
    [ note 1]
  ]

  [seealso ...]
]

The "concept" keyword could be extended to distinguish:

[concepttype MyConceptType1     [my concept description]
[conceptfunc MyConceptFunction1 [my concept description]

and the set of sub-sections would follow this distinction.

Motivation:

1) Concepts share the same well-defined sections and properties.

2) Currently, different libraries document it in different way,
what may decrease quality of documentation: lack of discoverability,
low expressiveness and transparency.

3) Unified structure of concepts documentation would be beneficial to
users, help to flatten learning curve, making it easier to compare
different concepts.

4) Predefined concepts block would serve as a useful guidance
and help developers to document concepts which are complex matter.

5) Output generator would get better control on how to present
concepts, properly order sections of concept specification, etc.

6) It would allow to include and automagically link to a legend
with explanation of the sections of concepts.
Something similar to  "The format of a concept page" provided here:
http://www.sgi.com/tech/stl/doc_introduction.html

7) Unified "look and feel", sounds as minor issue but isn't as we
learn and think in terms of patterns and similarities.

8) Validation. It would be possible to perform validation of concepts
specification, similarly as it is possible with list of variables:
For example, Quickbook will fail parsing a list with missing field:

[variablelist Variables
    [[`G`] ]
]

Looking forward comments.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org