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.
_______________________________________________
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
