Earlier this evening I found myself gawking at a strange confusion of letters and symbols that had appeared in my editor. What are these symbols, and where do they come from? What secret geometry governs their arrangement? Just what is this, anyway? I sat and stared, perplexed. The symbols stared back.
Soon my eyes adjusted to the strange contours of the glyphs, and I began to perceive a kind of rhythm or a structure to their ordering. Finally, I lit upon this enchanted hieroglyph:
@file
Of course! That's what this is -- a file! I wept with joy, and my heart soared with gratitude for this humble Doxygen tag, without which the ontology of our source code would be occult and irretrievable.
But soon my rapture gave way to creeping doubts: could we not, after all, do better?
I went to the drawing board. After several iterations (all agile, naturally), I came up with two tags that I think are very fine and that I'd like to see us adopt. Consider them:
@tag
This tag denotes a Doxygen tag. Like '@file', it answers the question, "What is this?". Answer: it is a Doxygen tag. It is not a banana. A car part, neither. If you thought it was a ceiling fan or a Python decorator, you were wrong -- dead wrong. Because it is a Doxygen tag.
@comment
This tag denotes a comment. It precisely identifies the purpose and discourse of the text which surrounds it. It tells you, "There is wisdom here. Stay a while and listen."
Here is a sample file header, demonstrating proper usage of these tags:
/** * Example * This file represents an example. * * @file * @ingroup examples * @comment * @tag */
The syntax is economical and expressive; the meaning eloquent and germane.
What do you think? Don't worry about the HTML representation for now -- we can worry about those later.
--- Ori Livneh ori@wikimedia.org
On Sat, 08 Jun 2013 00:42:40 -0700, Ori Livneh ori@wikimedia.org wrote:
/**
- Example
- This file represents an example.
- @file
- @ingroup examples
- @comment
- @tag
*/
Uhh, what extra meaning are @comment and @tag supposed to suggest?
@file already indicates that this comment block defines metadata and details about the whole file.
Ori Livneh ori@wikimedia.org
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.
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
On Sat, Jun 8, 2013 at 3:42 AM, Ori Livneh ori@wikimedia.org wrote:
@file
Of course! That's what this is -- a file! I wept with joy, and my heart soared with gratitude for this humble Doxygen tag, without which the ontology of our source code would be occult and irretrievable.
I should note that in MediaWiki's context this tag is useless. Doxygen will automatically realize that a file comment is a file comment. The actual purpose of the @file tag is if you have a project where you are constructing your documentation in a different file than the actual source code (yes, people do this). In other words, if all of your documentation is in docs/hello.txt and you want to document another file docs/test.php, then the @file tag should be used.
(quick, is it @param String $mystr or @param $myStr
{string} ?)
It is @param [type] $param. I have referred to the output, and it is indeed different. When Doxygen sees a type, it separates it from the parameter description and adds styling and whatnot.
*-- * *Tyler Romeo* Stevens Institute of Technology, Class of 2016 Major in Computer Science www.whizkidztech.com | tylerromeo@gmail.com
On 06/08/2013 03:42 PM, Tyler Romeo wrote:
On Sat, Jun 8, 2013 at 3:42 AM, Ori Livneh ori@wikimedia.org wrote:
@file
Of course! That's what this is -- a file! I wept with joy, and my heart soared with gratitude for this humble Doxygen tag, without which the ontology of our source code would be occult and irretrievable.
I should note that in MediaWiki's context this tag is useless.
Thanks, edited accordingly: https://www.mediawiki.org/w/index.php?title=Manual:Coding_conventions/PHP&am...
It is @param [type] $param. I have referred to the output, and it is indeed different. When Doxygen sees a type, it separates it from the parameter description and adds styling and whatnot.
Yes, I fixed the coding conventions accordingly a while back.
Matt Flaschen
On Sat, Jun 8, 2013 at 12:42 PM, Tyler Romeo tylerromeo@gmail.com wrote:
Doxygen will automatically realize that a file comment is a file comment.
You'd think so, but this appears to not be the case:
<ori-l> http://noc.wikimedia.org/~olivneh/doxygen_testcases.tar.gz has four php files <ori-l> i'm guessing 1, 2 & 3 produce identical output, no idea about 4 <ori-l> (the hypothesis is that a comment block doesn't need '@file' if it's freestanding and at the top of the file it's describing) <TimStarling> only case 1 and 3 are in the file list, case 2 and 4 are missing <TimStarling> this is with default configuration with doxygen 1.7.6.1
On 09/06/13 05:42, Tyler Romeo wrote:
On Sat, Jun 8, 2013 at 3:42 AM, Ori Livneh ori@wikimedia.org wrote:
@file
Of course! That's what this is -- a file! I wept with joy, and my heart soared with gratitude for this humble Doxygen tag, without which the ontology of our source code would be occult and irretrievable.
I should note that in MediaWiki's context this tag is useless. Doxygen will automatically realize that a file comment is a file comment. The actual purpose of the @file tag is if you have a project where you are constructing your documentation in a different file than the actual source code (yes, people do this). In other words, if all of your documentation is in docs/hello.txt and you want to document another file docs/test.php, then the @file tag should be used.
Both my testing and the Doxygen manual indicate that this is not the case. If you omit the @file, then the relevant doc comment does not appear in the generated HTML.
-- Tim Starling
On Wed, Jun 12, 2013 at 1:51 AM, Tim Starling tstarling@wikimedia.orgwrote:
Both my testing and the Doxygen manual indicate that this is not the case. If you omit the @file, then the relevant doc comment does not appear in the generated HTML
Interesting. Guess I was wrong. Sorry about that.
*-- * *Tyler Romeo* Stevens Institute of Technology, Class of 2016 Major in Computer Science www.whizkidztech.com | tylerromeo@gmail.com
wikitech-l@lists.wikimedia.org