Patches to add doxygen support to build and add some comments.

[Ryan McLean]

Jef,

|When building outside the source tree (which is my personal default),
|nothing gets documented. So this will need some more improvements.

I have everything in ~/workspace/libdc and run make from there so only
tested that, most likely its becuase the Doxyfile.in uses relative paths I
probably just need to play with them a bit to get that corrected.

|Is there a reason why you did reformat the existing documentation? I
|prefer the original format with the javadoc style syntax.

The first file I started on either had no defined style or used the c syntax
so I just continued with that and was trying to be consistant.
Also the @param[in] didnt seem to actually work/put the [in] bit anywhere useful in the
documentation, so it seemed redundant.
I'm (very) slightly more familiar with the c style, but I can use the other format if that is preferred.

|You also started to document some internal stuff. But none of that is
|supposed to end up in the documentation! The part that needs to be
|documented are the public header files.

I started there as I was trying to understand how libdivecomputer acutally works and
figured all should be documented. I thought there would be two types of developers:
1) those using your public API such as subsurface
2) those wanting to contribute to libdivecomputer itself.
Maybe should have two subfolders in the docs dir; public API and fulldoc.

Regards,

Ryan


________________________________
From: Jef Driesen <jef at libdivecomputer.org>
Sent: 04 November 2016 12:27:45
To: Ryan McLean
Cc: devel at libdivecomputer.org
Subject: Re: Patches to add doxygen support to build and add some comments.

Ryan,

I've always wanted to improve the documentation and generate manuals,
but never really had (or made) time for it. I quickly checked your
patches, and have a few comments/questions:

When building outside the source tree (which is my personal default),
nothing gets documented. So this will need some more improvements.

Is there a reason why you did reformat the existing documentation? I
prefer the original format with the javadoc style syntax.

You also started to document some internal stuff. But none of that is
supposed to end up in the documentation! The part that needs to be
documented are the public header files.

Jef
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://libdivecomputer.org/pipermail/devel/attachments/20161104/c916cbd4/attachment.html>