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

[Anton Lundin]

On 04 November, 2016 - Ryan McLean wrote:

> 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.
> 

One can use the
http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdinternal to
separate whats "internal" and whats external documentation.

That way one can "hide" internal api's when generating the "normal"
documentation, but still have them documented the same way, and include
them when generating the "internal" documentation for libdivecomputer.


//Anton


-- 
Anton Lundin	+46702-161604