<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I guess it depends on what you mean by "published Doxygen".<br>
I was meaning "so-called documentation made available to people outside<br>
the project generated using Doxygen."<br></blockquote><div><br></div><div><div>I believe one of the main issues with projects like Doxygen is that they don't make a strong distinction syntax-wise between documentation and code comments. After all, the two have different targets: the former is for users of your API, the latter is for readers of your code. And without having a strong distinction between the two, programmers do not find themselves in the proper mindset when writing documentation. They write documentation as if developers were also reading the source code which is the opposite of what documentation is meant to be.</div></div><div><br></div><div>That's why I dislike the term "doc comments". Is it documentation or is it a comment?</div><div><br></div><div>I have also seen similar confusion in the Ruby community, where there isn't also a strong distinction between code comment and documentation. I have heard developers saying "code should be self-documenting" as a justification for not writing documentation while they probably meant that "code should be self-explanatory" to imply that excessive code comments may be a code smell, such as:</div><div><br></div></div></div><blockquote style="margin:0 0 0 40px;border:none;padding:0px"><div class="gmail_extra"><div class="gmail_quote"><div># Removes the discount from the tag price</div></div></div></blockquote><blockquote style="margin:0 0 0 40px;border:none;padding:0px"><div class="gmail_extra"><div class="gmail_quote"><div>final_price = tag_price - discount </div></div></div></blockquote><div class="gmail_extra"><div class="gmail_quote"><div><br></div><div>Some languages however, like Python and Clojure, do allow documentation to be written alongside the source, but they have a strong distinction between what is documentation and what is a code comment. They also make that documentation part of the function reflection API, making it easy to retrieve and format that documentation, even in the language repl.</div><div><br></div><div>In any case, reference documentation is only one of aspect of writing documentation. Regardless if the reference documentation is written at the source or separately, most libraries also need at least one guide/tutorial/free-form introduction.</div><div><br></div></div></div></div>