On 2013-06-08 5:29 AM, "S Page" spage@wikimedia.org wrote:
Perhaps Ori is pointing out that doxygen (and jsduck) require needless verbiage. The tools aren't smart enough to infer obvious information from source on their own (or maybe they are but you're not sure and you see other comments using these symbols so you copy and paste), so you wind up repeating information in "doc generation syntax".
And to what end? I view doxygen as an external test that we're being consistent in comments (quick, is it @param String $mystr or @param
$myStr
{string} ?) but I never actually refer to the generated output. Does anyone? Until someone builds a browser bridge that automatically scrolls the right HTML into view as you move around in your editor and automatically regenerates the HTML as you type, I don't see my habits changing.
If web search engines could understand the generated documentation and ranked it higher in search results it would be more useful and used more.
Thank you for that email Ori. It was beautiful.
To answer S's question - I mostly look at the code, but I do use the html docs occasionally. I used them quite extensively when I was a newbie first learning about mediawiki. I also regularly link to them when people in irc say things like "how do I do x".
-bawolff