[apex] Re: Documentation
- From: Patrick Oppenlander <patrick.oppenlander@xxxxxxxxx>
- To: dev@xxxxxxxxxxxx
- Date: Tue, 23 Mar 2021 08:39:56 +1100
On Tue, Mar 23, 2021 at 8:18 AM Michael Alleblas <malleblas@xxxxxxxxxxx> wrote:
I am adding unfinished parts to the CCM module of the i.MX RT10xx to support
other clocks. In the process I have added a lot of code in Doxygen format in
my fork.
OK, make sure you're on top of master as I recently made some changes to ccm.h.
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?
One thing I did notice was the final part of the COPYRIGHT document states:
The omission of copyright and license comments in each file is in the
interest of
source tree size.
I didn't think source code tree size was an issue these days, but I am
probably oblivious to the reasoning behind it.
Not really worried about disk usage, more about keeping the noise of
big copyright statements out of each source file. IMHO they add no
value, especially as the project is under a very permissive license.
You'll notice that some of the files still carry historic copyright
notices which can't be removed.
If documentation is something that will be used, is there a particular system
or style or both already envisioned? As mentioned, I have already started
using Doxygen believing it to be a fairly well used and supported system with
plenty of tooling support. I didn't want to go too far down the rabbit hole
in a direction different to that of the project.
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.
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?
Is there a way to include external content into doxygen's output?
-Mike
Patrick
Other related posts:
