[Boost-docs] Details of synopsis section

Subject: [Boost-docs] Details of synopsis section
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2010-02-07 23:07:13

Hi,

I have a few questions about synopsis section in a reference.

1) Reference node in a documentation

Some documentations have Reference section based on physical structure
of library, as a list of clickable headers, for example Program Options,
Date Time or Property Tree.
Click on a header leads to do short version of synopsis with
only a prototype of type or function.
Click on type/function name leads to long version with details
about public members of a type, function parameters, etc.

Some libraries like Range or Fusion generate Reference not based
on headers but more on, let's say, logical structure of
library elements: functions, metafunctions or data types, algorithms,
iterators, etc. It looks like this approach is preferred in newer
documentations based on Quickbook.

Which option of Reference section is preferred?

I'm working on Quickbook-based documentation of Boost.Geometry
and having large number of headers, it seems he first option would not
work well, so I'm organizing Reference not following physical
structure but logical.

2) Specification of namespace

Some of the Boost libraries explicitly specify namespace
in a type / function synopsis, for example, Optional
or Quickbook-based docs for Range.
Some, however, if not most, do not specify it.
What is the proper way, with or without namespace?

ATM, in synopsis sections, I include full namespace encompassing
particular element of library:

[heading Synopsis]

  namespace boost { namespace geometry {
    class my_class
    {
       ...
    };
  }}

3) Synopsis details

I understand that a synopsis of class or class templates
should include all public members and later all those
members are described in details. Is that correct way?

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