Remove consecutive @see in doc comments
neochief - May 28, 2008 - 11:44
| Project: | Drupal |
| Version: | 7.x-dev |
| Component: | documentation |
| Category: | bug report |
| Priority: | minor |
| 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.