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
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@libdivecomputer.org Sent: 04 November 2016 12:27:45 To: Ryan McLean Cc: devel@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
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:
- those using your public API such as subsurface
- 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
On 07-11-16 13:05, Anton Lundin wrote:
On 04 November, 2016 - Ryan McLean wrote:
|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:
- those using your public API such as subsurface
- 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.
It's even more simple: only the header files in the include directory are public, everything else is private.
Jef
On 08 November, 2016 - Jef Driesen wrote:
On 07-11-16 13:05, Anton Lundin wrote:
On 04 November, 2016 - Ryan McLean wrote:
|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:
- those using your public API such as subsurface
- 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.
It's even more simple: only the header files in the include directory are public, everything else is private.
So you're saying there are no cases what so ever for documenting the internal functions of libdivecomputer?
//Anton
On 08-11-16 20:48, Anton Lundin wrote:
On 08 November, 2016 - Jef Driesen wrote:
On 07-11-16 13:05, Anton Lundin wrote:
On 04 November, 2016 - Ryan McLean wrote:
|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:
- those using your public API such as subsurface
- 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.
It's even more simple: only the header files in the include directory are public, everything else is private.
So you're saying there are no cases what so ever for documenting the internal functions of libdivecomputer?
Of course not. I'm just saying that the distinction between public and private can be based on the directory.
Jef
Depends on previous patches as I'm not sure how to just create a single patch for that one file with Git.
________________________________ From: devel devel-bounces@libdivecomputer.org on behalf of Jef Driesen jef@libdivecomputer.org Sent: 08 November 2016 20:01 To: Anton Lundin Cc: devel@libdivecomputer.org Subject: Re: Patches to add doxygen support to build and add some comments.
On 08-11-16 20:48, Anton Lundin wrote:
On 08 November, 2016 - Jef Driesen wrote:
On 07-11-16 13:05, Anton Lundin wrote:
On 04 November, 2016 - Ryan McLean wrote:
|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:
- those using your public API such as subsurface
- 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.
It's even more simple: only the header files in the include directory are public, everything else is private.
So you're saying there are no cases what so ever for documenting the internal functions of libdivecomputer?
Of course not. I'm just saying that the distinction between public and private can be based on the directory.
Jef _______________________________________________ devel mailing list devel@libdivecomputer.org http://libdivecomputer.org/cgi-bin/mailman/listinfo/devel
On 09-11-16 00:06, Ryan McLean wrote:
Depends on previous patches as I'm not sure how to just create a single patch for that one file with Git.
I applied part of your patches with the build infrastructure. I made a few changes to move the makefile bits to their own directory, and fixed a few issues as well. I left out the actual documentation changes, because I prefer the existing javadoc style.
So the build infrastructure is in place now. Thanks for your work!
Jef
-
Anton Lundin -
Jef Driesen -
Ryan McLean