documentation format

[Ralf Hemmecke]

Peter,

I've seen quite a number of new categories/domains/packages in your
patch series. I still didn't have enough time to go through in more
detail and comment on them.

But to be really useful, it would be better if your new types were
documented. But that's not my concern now.

My question more concerns the format of the ++ docstrings.
I would somehow be happy, if they could be easily extracted (maybe a
comiler switch "-f docstring"). I would be even more happy, if they
could be extracted into a RestructuredText format. Of course, for that
it would be best if we agree on the convention that RestructuredText is
the format of the ++ docstrings.

Any pros and cons? Other ideas?

Ralf