Jump to:
| Project: | API |
| Version: | 6.x-1.x-dev |
| Component: | Code |
| Category: | feature request |
| Priority: | major |
| Assigned: | Unassigned |
| Status: | needs work |
Issue Summary
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.
| Attachment | Size |
|---|---|
| api-section-subsection-ref.patch | 3.12 KB |
Comments
#1
Right 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?
#2
Right 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.
#3
You 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.
#4
I 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
#5
Ah, 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.
#6
I have the feeling that drumm will shortly be asking for an addition to the patch: to add these sections to the tests.
#7
(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.
#8
#9
I'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.