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).

Files: 
CommentFileSizeAuthor
#10 add-section-tags-1811520-10.patch6.8 KBJacobSanford
PASSED: [[SimpleTest]]: [MySQL] 56,343 pass(es).
[ View ]
#10 interdiff_6-10.txt3.69 KBJacobSanford
#7 interdiff_2-6_fixed.txt6.91 KBJacobSanford
#6 add-section-tags-1811520-6.patch6.75 KBJacobSanford
PASSED: [[SimpleTest]]: [MySQL] 56,412 pass(es).
[ View ]
#6 interdiff_2-6.txt7.53 KBJacobSanford
#2 use_new_section_tags-1811520-2.patch2.43 KBlirantal
PASSED: [[SimpleTest]]: [MySQL] 49,649 pass(es).
[ View ]

Comments

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()

StatusFileSize
new2.43 KB
PASSED: [[SimpleTest]]: [MySQL] 49,649 pass(es).
[ View ]

Is this what you had in mind?

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.

Assigned:Unassigned» lirantal

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.

Status:Needs work» Needs review
StatusFileSize
new7.53 KB
new6.75 KB
PASSED: [[SimpleTest]]: [MySQL] 56,412 pass(es).
[ View ]

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.

StatusFileSize
new6.91 KB

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

Status:Needs review» Needs work

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"?

Assigned:lirantal» JacobSanford
Status:Needs work» Needs review
StatusFileSize
new3.69 KB
new6.8 KB
PASSED: [[SimpleTest]]: [MySQL] 56,343 pass(es).
[ View ]

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.

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.

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.