Re: [Wikitech-l] Doxygen tags - a proposal
On Wed, Jun 12, 2013 at 1:51 AM, Tim Starling tstarl...@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 | tylerro...@gmail.com ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Doxygen tags - a proposal
On Sat, Jun 8, 2013 at 12:42 PM, Tyler Romeo tylerro...@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 ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Doxygen tags - a proposal
On 09/06/13 05:42, Tyler Romeo wrote: On Sat, Jun 8, 2013 at 3:42 AM, Ori Livneh o...@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 ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
[Wikitech-l] Doxygen tags - a proposal
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 o...@wikimedia.org ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Doxygen tags - a proposal
On Sat, 08 Jun 2013 00:42:40 -0700, Ori Livneh o...@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 o...@wikimedia.org -- ~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://danielfriesen.name/] ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Doxygen tags - a proposal
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
Re: [Wikitech-l] Doxygen tags - a proposal
On 2013-06-08 5:29 AM, S Page sp...@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
___
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Doxygen tags - a proposal
On Sat, Jun 8, 2013 at 3:42 AM, Ori Livneh o...@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 | tylerro...@gmail.com
___
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: [Wikitech-l] Doxygen tags - a proposal
On 06/08/2013 03:42 PM, Tyler Romeo wrote: On Sat, Jun 8, 2013 at 3:42 AM, Ori Livneh o...@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/PHPdiff=nextoldid=705147 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 ___ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
