Re: [Boost-docs] Details of synopsis section

Subject: Re: [Boost-docs] Details of synopsis section
From: Daniel James (daniel_james_at_[hidden])
Date: 2010-02-08 07:33:25

On 7 February 2010 23:07, Mateusz Loskot <mateusz_at_[hidden]> wrote:
>
> 1) Reference node in a documentation
>
> Some documentations have Reference section based on physical structure
> of library, as a list of clickable headers [...]

> Some libraries like Range or Fusion generate Reference not based
> on headers but more on, let's say, logical structure of
> library elements [...]

> Which option of Reference section is preferred?

That's up to you. Do whatever you think is the best way to document
your library.

> 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?

With a namespace, sicne you should be able to see everything you need
for a class or function on its page in the reference documentation.

> 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?

That's generally how to do it but there aren't rigid rules for doing
this, you should use your judgement. There are some guidelines, but
they are just guidelines:

http://www.boost.org/doc/libs/1_42_0/more/writingdoc/structure.html

Daniel