I just added some new functionality to the API module (which should be deployed on api.drupal.org sometime soon), which allows us to use @section and @subsection tags in our API documentation, to break up long documentation into sections. Usage is documented here:
http://drupal.org/node/1354#sections

I know that we have a few topic/group pages in our API documentation that could really benefit from these new tags, and probably some really long function or hook pages as well. So this task entails:

a) Scan the existing topic/group pages and identify which ones could benefit from breaking up into sections. (And if anyone knows of any functions that need splitting up, they can be noted here too.)

b) Add the @section and @subsection tags as appropriate to the documentation identified in (a).

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon’s picture

Issue tags: +Novice

Whoops, forgot tag. :)

Also, here's a list of a few functions/hooks that I know of that I think could really benefit from sectionizing:

theme()
hook_menu()
t()

lirantal’s picture

Is this what you had in mind?

webchick’s picture

Status: Active » Needs review

Marking needs review, since it's a patch. :) This way the testbot will pick it up, and other reviewers will know to take a peek.

lirantal’s picture

Assigned: Unassigned » lirantal
jhodgdon’s picture

Status: Needs review » Needs work

Thanks for the patch -- it's a good start!

A few notes:
- I think the section identifiers should be better than sec_a, sec_b, etc... more like sec_func_args etc. This will make it easier if we need to make links between sections.
- I am not sure that the section names added to theme() in this patch are perfect yet. For instance, the first one says "Function arguments", but that paragraph is really mostly talking about registering theme hooks. And the "template files" section is really about the order of processing theme hooks.
- It's possible that with section headers, some of the documentation may need to be rewritten. For instance, the current theme() docs are written with a narrative flow from one paragraph to the next, but if there are sections, this should probably be revised.
- I don't think this patch should be removing the paragraph break that it removes.
- This patch only addresses the theme() function... We either need to make one big patch on this issue that adds section headers to everywhere that needs it (3 places have so far been identified), or we need to make separate issues for each place that needs headers, and provide a patch for each issue separately.

JacobSanford’s picture

Status: Needs work » Needs review
FileSize
7.53 KB
6.75 KB

As mentioned, this is clearly a small part of a large effort, but I've continued on by focusing on review points and expanding to 3 functions mentioned in OP. I would leave the language and 'flow' modifications, if any to someone else. For tech documentation, it seems to read OK.

JacobSanford’s picture

FileSize
6.91 KB

Disregard interdiff attached in #6. Accurate one attached below.

JacobSanford’s picture

Status: Needs review » Needs work
jhodgdon’s picture

I was not sure why you set it to "needs work", so I reviewed it. :) It's much better, thanks!

A few thoughts:

a) In the theme() function docs, I was wondering if the sub-sections "Hook Execution Order" and "Restrictions on Functions" should be called "Preprocessing for Template Files" and "Preprocessing for Theme Functions" respectively?

b) Also, the "Suggesting Alternate Functions" should really be "Suggesting Alternate Hooks", because they apply to theme templates as well as theme functions.

c) In the hook_menu() docs, I'm not very happy with the "Operators in Path" header. What does that mean? How about just calling it "Wildcards in Paths", and call the first sub-section "Simple Wildcards", and the next one "Auto-Loader Wildcards", and the _to_arg one "Argument Wildcards"?

JacobSanford’s picture

Assigned: lirantal » JacobSanford
Status: Needs work » Needs review
FileSize
3.69 KB
6.8 KB

Thanks for review! Recommended changes below.

I kept as 'needs work' due to point in #5 that we may want to consider and expand issue further to cover other large blocks. More than happy to mark as completed, however.

jhodgdon’s picture

Assigned: JacobSanford » jhodgdon
Status: Needs review » Reviewed & tested by the community

Looks good! I'll get it committed shortly. And I think having these pages done is enough for now. As people write longer documentation, hopefully they will use these pages as a model, or we can edit them later.

jhodgdon’s picture

Assigned: jhodgdon » Unassigned
Status: Reviewed & tested by the community » Fixed

Thanks again! Amazingly, this patch still applied, and worked for Drupal 7 too, so it's committed to 8.x and 7.x.

Automatically closed -- issue fixed for 2 weeks with no activity.