Handle consecutive @see in doc comments
neochief - May 28, 2008 - 11:44
| Project: | API |
| Version: | 6.x-1.x-dev |
| Component: | Parser |
| Category: | bug report |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | active |
Description
Handling @see are braking the summaries now. Take a look at search_box summary at this page:
http://api.drupal.org/api/file/modules/search/search.module/6
(there See alsosearch_box_form_submit() at the end)
To avoid this, we can add paragraph ending just before the See also header (and place paragpaph tag to the end to avoid breaking the code). After it all will be ok.
You can apply the patch in attachment.
| Attachment | Size |
|---|---|
| parser.inc_.patch | 670 bytes |
#1
I found another bug with @see. Take a look at:
http://api.drupal.org/api/group/themeable/6
There are @see after See also header. It happens because in API module is only one @see replasing to the proper values. My patch fixes both bugs.
#2
I can confirm the problem here, too: http://api.drupal.org/api/function/hook_aggregator_fetch/7
#3
i think i noticed some more of these... should this patch fix them all?
#4
This is apparently still a problem in the 6.x branch, since #2 still shows an extra @see.
#5
http://www.stack.nl/~dimitri/doxygen/commands.html#cmdsa says:
So:
<?php
/**
* This is bad.
*
* @see foo()
* @see bar()
*/
/**
* And this is good.
*
* @see foo(), bar()
*/
?>
And of course, just using @see inline, like this, should be written as a proper sentence. You can probably just remove the @ in many cases.
#6
Also found in the exact same Doxygen documentation:
http://www.stack.nl/~dimitri/doxygen/docblocks.html
/*** a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
There is no problem using multiple line @see's and it looks much better than using a comma list of them all on one line. This should move back to the api.module.
#7
It would be good to do some actual tests with Doxygen in this case, so we have sample input/output to test against. How does the order of @tags affect the output? What if the @see tags are not consecutive? We don't necessarily have to follow Doxygen exactly, but we should do predictable things for people coming from other projects.
A rewrite of the doc parser needs to be done at some point, hopefully with good test-cases for documenting and unit tests.
#8
+1 for multiple @see directives. We have places in core where 6 or more related functions are listed and it simply looks much better when each one is on a separate line.
We should also use @see, albeit ignored, in inline comments have a consistent pattern for how to refer to other things and not introducing countless of custom wordings for "See foo()" (without period), "See foo()." (with period), "See also foo()" (also), "See foo() for more information" (cruft), etc.
#9
Sounds like this is an API module issue then, that you want support for multiple @see directives?
#10
I still want to know how Doxygen itself handles this.
#11
I'm not sure this is enough for you to go on, but here's what the Doxygen site's doc says...
http://www.stack.nl/~dimitri/doxygen/docblocks.html shows this code block using JavaDoc style doc:
/*** a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
And the output -- http://www.stack.nl/~dimitri/doxygen/examples/jdstyle/html/class_test.html
The See Also section's HTML is:
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="class_test.html#99f2bbfac6c95612322b0f10e607ebe5" title="A constructor.">Test()</a> <p>
<a class="el" href="class_test.html#2b0a62f1e667bbe8d8cb18d785bfa991" title="A destructor.">~Test()</a> <p>
<a class="el" href="class_test.html#3edb9fdc1e9f0d5274b57386ab03704c" title="A pure virtual member.">testMeToo()</a> <p>
<a class="el" href="class_test.html#3085f973ef857d85d647bf04e89760d0" title="a public variable.">publicVar()</a> </dd></dl>
Which renders as:
~Test()
testMeToo()
publicVar()
#12
Okay, so @see needs a new column in {api_documentation}, the string resuffling won't cut it anymore. The parsing will probably follow the pattern of @param. And of course the templates need to render this.