<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="Generator" content="Microsoft Exchange Server">
<!-- converted from text --><style><!-- .EmailQuote { margin-left: 1pt; padding-left: 4pt; border-left: #800000 2px solid; } --></style>
</head>
<body>
<meta content="text/html; charset=UTF-8">
<style type="text/css" style="">
<!--
p
{margin-top:0;
margin-bottom:0}
-->
</style>
<div dir="ltr">
<div id="x_divtagdefaultwrapper" style="font-size:12pt; color:#000000; font-family:Calibri,Arial,Helvetica,sans-serif">
<p></p>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">Jef,</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px"><br>
</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">|When building outside the source tree (which is my personal default), </span></font><br>
<font size="1" color="#212121"><span style="font-size:13.32px">|nothing gets documented. So this will need some more improvements.</span></font><br>
</div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px"><br>
</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">I have everything in ~/workspace/libdc and run make from there so only </span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">tested that, most likely its becuase the Doxyfile.in uses relative paths I </span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">probably just need to play with them a bit to get that corrected. </span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px"><br>
</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">|Is there a reason why you did reformat the existing documentation? I </span></font><font size="1" color="#212121"><span style="font-size:13.32px"><br>
</span></font><font size="1" color="#212121"><span style="font-size:13.32px">|prefer the original format with the javadoc style syntax</span></font><font size="1" color="#212121"><span style="font-size:13.32px">.</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px"><br>
</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">The first file I started on either had no defined style or used the c syntax </span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">so I just continued with that and was trying to be consistant. </span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">Also the @param[in] didnt seem to actually work/put the [in] bit anywhere useful in the </span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">documentation, so it seemed redundant.</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">I'm (very) slightly more familiar with the c style, but I can use the other format if that is preferred.</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<br>
</div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">|You also started to document some internal stuff. But none of that is </span></font><font size="1" color="#212121"><span style="font-size:13.32px"><br>
</span></font><font size="1" color="#212121"><span style="font-size:13.32px">|supposed to end up in the documentation! The part that needs to be </span></font><font size="1" color="#212121"><span style="font-size:13.32px"><br>
</span></font><font size="1" color="#212121"><span style="font-size:13.32px">|documented are the public header files.</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px"><br>
</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">I started there as I was trying to understand how libdivecomputer acutally works and </span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">figured all should be documented. </span></font><font size="1" color="#212121"><span style="font-size:13.32px">I thought there would be</span></font><font size="1" color="#212121"><span style="font-size:13.32px"> two
types of developers:</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">1) those using your public API such as subsurface</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">2) those wanting to contribute to libdivecomputer itself.</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">Maybe should have two subfolders in the docs dir; public API and fulldoc.</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px"><br>
</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">Regards,</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px"><br>
</span></font></div>
<div style="font-family:Calibri,Arial,Helvetica,sans-serif; font-size:16px; margin-top:0px; margin-bottom:0px">
<font size="1" color="#212121"><span style="font-size:13.32px">Ryan</span></font></div>
<br>
<p></p>
</div>
<hr tabindex="-1" style="display:inline-block; width:98%">
<div id="x_divRplyFwdMsg" dir="ltr"><font face="Calibri, sans-serif" color="#000000" style="font-size:11pt"><b>From:</b> Jef Driesen <jef@libdivecomputer.org><br>
<b>Sent:</b> 04 November 2016 12:27:45<br>
<b>To:</b> Ryan McLean<br>
<b>Cc:</b> devel@libdivecomputer.org<br>
<b>Subject:</b> Re: Patches to add doxygen support to build and add some comments.</font>
<div> </div>
</div>
</div>
<font size="2"><span style="font-size:10pt;">
<div class="PlainText">Ryan,<br>
<br>
I've always wanted to improve the documentation and generate manuals, <br>
but never really had (or made) time for it. I quickly checked your <br>
patches, and have a few comments/questions:<br>
<br>
When building outside the source tree (which is my personal default), <br>
nothing gets documented. So this will need some more improvements.<br>
<br>
Is there a reason why you did reformat the existing documentation? I <br>
prefer the original format with the javadoc style syntax.<br>
<br>
You also started to document some internal stuff. But none of that is <br>
supposed to end up in the documentation! The part that needs to be <br>
documented are the public header files.<br>
<br>
Jef<br>
</div>
</span></font>
</body>
</html>