Re: Ada and Doxygen

[sjw <simon.j.wright@mac.com>]

On Feb 26, 8:04 pm, Vadim Godunko <vgodu...@gmail.com> wrote:

> Qt's uses another way. There are no comments in headers at all. This
> makes header files clean - it is very important for overview of the
> class. All comments are placed in the implementation files. Special
> tool parse both headers and implementation files, construct list of
> classes, its methods/signals/slots/etc; then parse implementation
> files and extracts description for each entity; links classes/methods/
> slots/signals with their descriptions and construct complete
> documentation in HTML form, which can be hosted somewhere or read by
> browser. After that, another tool pack this documentation and all
> related resources into the one "database" which can be registered in
> the Qt Assistant to extend useful of it (Qt Assistant allows to do
> full text search for example). And even it is not a last step, when
> you use Qt Creator (IDE for Qt) and stay somewhere in the code, you
> can click key and Qt Creator opens description of class/method you
> stay on in the Qt Assistant documentation. It is very fast and useful!

I think you're saying that humans never need to read the .h files at
all, because tools make it possible to read the documentation where/
when you need to, in whatever form is most appropriate.

Nothing wrong with the outcome, but (it seems to me that) if the Qt
scheme had started from having full descriptions in the .h files and
the tools worked in that environment instead, you would be in
*exactly* the same position as now.

I find it frustrating going from the package specs in the LRM to
somewhere down-page which describes what the code actually means.