[apex] Re: Documentation

  • From: Michael A <mikey+lists@xxxxxxxxxxx>
  • To: dev@xxxxxxxxxxxx
  • Date: Wed, 24 Mar 2021 12:40:50 +1100

Hi Pat,

Personally I don't see an advantage to having doxygen tags in the
comments unless we're planning on running doxygen over the project,
which, at the moment, we don't.

Do you have plans to generate doxygen output?

I didn't have any immediate plans to, however if the project was
projected to use Doxygen or some other system, then I would happily
work on including that content where possible.

I had imagined the documentation consisting of comments in the code
and some files describing how various things work (similar to the
Documentation directory in the Linux tree).

I find reading doxygen output a bit hard. If I'm in the code I can
read the comments. If I'm looking for something which gives me a
higher level description of how the code goes together I've rarely
found it in generated doxygen stuff.

I agree on the readability, although I believe this should be able to
be rectified with configuration or templates or both. I have seen some
projects where their Doxygen output was excellent, such as the OpenCV
project.

The latter statement is more indicative of the way that the
documentation is used in my opinion. If it is basic documentation with
no context, discussion of philosophy etc, then it can be quite useless
with no additional benefit over just reading the code.

We would also need somewhere to host the generated docs and a process
for automatically keeping them up to date.

Does doxygen still turn the comments into an awful mess of tags or is
there a cleaner way to do it now?
Doxygen does pick up a lot of "normal" type comments and has automated
defaults as to what that maps to in the way of tags. There are also
some small changes that can be made to comments to change their
behaviour which still looks natural.

Alternatively you can create an export of the code to a set of
external files called "tag files" which can be documented. This is not
only useful for separating out the documentation from the working
code, it can also be used to document external source code for which
you do not have access to change.

Is there a way to include external content into doxygen's output?
Fairly certain but not sure of the mechanism.

I will contribute my code without Doxygen for now. At a later date I
will rethink the use of Doxygen, taking into account some of the
points you made regarding hosting, generation, maintenance etc.

-Mike

Other related posts: