Re: [Boost-docs] Query regarding boostbook and documentation

Subject: Re: [Boost-docs] Query regarding boostbook and documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-01-09 16:51:32

On 1/9/16 6:27 AM, Raffi Enficiaud wrote:

> I may add this:
>
> https://github.com/boostorg/test/tree/master/doc
>
> that I wrote for inciting ppl to contribute to documentation. This is
> quickbook oriented, but it is a simple enough complete example of
> quickbook+doxygen documentation.
>
> Hope this helps,

I just took a quick look at it but it looks interesting to me.

In the incubator is basically discourage people from using
the boost tool chain as I think there is a simpler more
expedient approach which get's library authors on the
right track faster but leaves them with something that
the could easily transition to boost tools if they
get their library accepted.

I've also discourages the usage of DOxygen because
I don't believe that, as delivered, it doesn't
support documentation of type requirements which
I believe is essential.

Having said the above, I have to concede that I've
failed to gain acceptance of my ideas to the extent
I would have hoped.  So I'm interested in the following

a) better support/explanation for those who want/need
to use boost.  There is some documentation at Boost.org
but it needs to be more idiot proof.  Looks like this
is what your aiming at here.

b) DOxygen is here to stay.  I would like to see
someone take up the challenge of making an extension
which supports type requirements (aka concepts).
 From the users point of view, this would look like
the following:

1) Show how to create concept checking classes be it
via boost concept checking and/or concepts lite.
Users would write these as C++ header files.

2) Add DOxygen markup using the cited DOxygen
extended markup

3) Follow procedures (presumably described in a)
above, to integrate DOxygen output into documentation.

At this point we'd have support for type requirements
in both the code and documentation.  This would
improve both code and documentation and make the
documentation much more likely to be correct and
complete and also make documentation easier to write.

One final step would be consolidate all this
information (along with any existing information)
in to a coherent whole and place it on the website.
Getting the website more useful for projects of
this nature is another of my current holy quest.
I've not made progress here.  I just have to keep
harping on the subject.

Robert Ramey

>
> Best regards,
> Raffi