Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.This patch grew out of a use case at #648218: Make API changes in Drupal core be nodes (and was originally posted in comment #31 of that issue), but regardless of what happens there it is a potentially useful feature for the API module in its own right.
The patch allows @ref, @section and @subsection (see http://www.doxygen.nl/commands.html) Doxygen tags to be used. The use case is described in the issue linked to above; it allows different sections and subsections to be created within a long section of documentation and on-page links to be generated between them.
The attached patch is against the latest dev version of api.module; I wrote the patch originally a while ago and haven't kept up with the latest changes in api.module since then, but functionally the patch seems to work fine as is.
| Comment | File | Size | Author |
|---|---|---|---|
| api-section-subsection-ref.patch | 3.12 KB | David_Rothstein |
Comments
Comment #1
jhodgdonRight now, we don't have any really long doc items that would benefit from having these tags, but there's not a compelling reason they shouldn't be allowed. I'm not sure the use case in the referenced issue will be adopted...
I am also not sure the patch is complete -- seems like it would need some CSS and formatting?
Comment #2
David_Rothstein CreditAttribution: David_Rothstein commentedRight now I don't see any CSS in the api.module for generic things like h1/h2/etc tags (and there shouldn't be), so I don't see any reason we would need to add it here? Or did you mean something else?
It's possible I should have used h2 and h3 tags here though (rather than h3 and h4), just looking at the overall document this generates.
Comment #3
jhodgdonYou are right, my mistake.
Since @param and @return and the other sections like that are currently using H3, the Section and Subsection tags should probably be using H3 and H4. I don't think we want them to be bigger/stronger headings than the Return Values, Related Functions, etc.
Comment #4
jhodgdonI actually just came across a place that would benefit from @section: the t() documentation page, which is kind of unwieldy. I'm currently rewriting it, and I think if it used @section, it would be much easier to read.
http://api.drupal.org/api/drupal/includes--bootstrap.inc/function/t/7
Comment #5
David_Rothstein CreditAttribution: David_Rothstein commentedAh, right! Now I remember - that is exactly why I used H3 and H4 in the first place. (So the fact that the document jumps from H1 directly to H3 is basically a preexisting issue.)
It's good to hear there is already another use case.
Comment #6
jhodgdonI have the feeling that drumm will shortly be asking for an addition to the patch: to add these sections to the tests.
Comment #7
drumm(Sorry for the slow review, reviewed this on an airplane and forgot about it.)
I am considering this separate from #648218: Make API changes in Drupal core be nodes, it is a good addition regardless of that issue. People working in that issue have spent more time thinking about the issue than me, I'll let them handle it; I do encourage keeping it simple.
This patch:
- Needs unit tests. Add example to tests/sample/...; tests to tests/api_update_branch_php.test, which has a few @tags.
- There is a mismatched closing h4.
- @ref search needs preg_...() and API_RE_TAG_START.
Comment #8
drummComment #9
jhodgdonI'm reviving this issue. I think we should go ahead and add this feature. The patch undoubtedly needs a reroll as well as the fixes noted in comment #7.
Comment #10
jhodgdonI'm working on this today.
I took a look at the official Doxygen documentation http://www.doxygen.nl/commands.html and the section/subsection tags are only supposed to be supported on "@page" pages. We don't have those... The closest we have is the group/topic tags. But I don't think this is really a problem, or that we need to restrict the use of these tags to just being in one type of documentation block.
Also, the docs don't really specify (but kind of imply, as was done in the patch above) that @ref only works within the same page that has the @section and @subsection tags. I think that is reasonable.
Comment #11
jhodgdonOK, that was easy. I was able to pretty much use the patch David supplied nearly 2 years ago, with changes as suggested by drumm in #7, and with the addition of some tests. (In a separate commit, I also updated the README and help so that they no longer list specific tags -- we should just maintain that documentation on http://drupal.org/node/1354). So, this is fixed! I'll go update node/1354 with this information, and then we can have a Core docs issue to use these new tags (hopefully api.d.o will be running this new code shortly).
Comment #12
jhodgdonwhoops. Wrong version. :)