Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
Problem/Motivation
Part of meta-issue #1310084: [meta] API documentation cleanup sprint.
Proposed resolution
Correct the following in includes
files beginning with D-G:
- Ensure that each file has an
@file
docblock. - Ensure that all
@return
lines are preceded by a blank line. - Ensure that
@see
and@ingroup
lines are always at the end of docblocks. - Ensure that all lines in doxygen blocks are 80 characters or fewer (excluding the terminal newline).
- Ensure that all functions, classes, interfaces, and methods have one-line summaries that are clear, use the correct verb tense, and follow specific standards in http://drupal.org/node/1354.
- Make incidental style and grammar corrections only to those docblocks already being updated.
Remaining tasks
Followups
@return formatting
- errors.inc
Optional parameters not documented properly
- file.inc
List formatting
- file.inc
Other followups
- Batch API functions probably do not belong in
form.inc
anymore--FAPI dependencies should be removed. - Add defgroup for stream wrapper registry?
Comment | File | Size | Author |
---|---|---|---|
#29 | d-g-1317620-d7-29.patch | 42.22 KB | Albert Volkman |
#23 | d-g-23.patch | 48.79 KB | xjm |
#23 | interdiff.txt | 539 bytes | xjm |
#19 | d-g-full.patch | 48.79 KB | xjm |
#19 | interdiff-graph.txt | 642 bytes | xjm |
Comments
Comment #1
xjmCleanup for character limit, lines above
@return
, and@see
/@ingroup
positioning. No fixes to summaries or file docblocks yet. Waiting on #1315992: No standard for documenting menu callbacks and perhaps #1317826: Provide general documentation standard for callbacks.Comment #2
xjmUntagging.
Comment #3
Lars Toomre CreditAttribution: Lars Toomre commentedThere is an indentation issue here in the corrected documentation for form_error():
Comment #4
xjmThis patch is still marked needs work, meaning it's not finished. Also, this and the other two through Z are actually going to be discarded and re-done, so don't waste time on 'em. :)
Comment #5
Lars Toomre CreditAttribution: Lars Toomre commentedJust saw your comment now about how this and other two are going to be redone. I will hold off on further comments until then.
Comment #6
xjmPostponing for core directory change.
Comment #7
xjmGoing to roll this in steps with interdiffs so that it's easier to review.
Comment #8
xjmFirst, just moving the @see to the end.
Comment #9
xjmAdding blank lines above @return.
Comment #10
xjmRewrapping lines over 80 chars + \n for non-summaries.
Comment #10.0
xjmUpdated issue summary.
Comment #10.1
xjmUpdated issue summary.
Comment #11
xjmCleaning up
@file
blocks. Next comes the fun part.Comment #12
xjmSummary corrections through
errors.inc
.Comment #12.0
xjmUpdated issue summary.
Comment #12.1
xjmUpdated issue summary.
Comment #12.2
xjmUpdated issue summary.
Comment #12.3
xjmUpdated issue summary.
Comment #13
xjmSummary corrections through
file.inc
.I also removed a floating docblock with nothing attached to it--at first it looked like it might be a defgroup, but it's actually in the middle of another defgroup. So I added that to the followup list.
Comment #14
aspilicious CreditAttribution: aspilicious commentedAfter multiple @see there should be a newline. *I think*
Same in a few more places
-8 days to next Drupal core point release.
Comment #15
xjmThis patch isn't done yet.
Comment #16
xjm@aspilicious and I checked and his comment in #14 is actually not accurate, at least in the current standard. See, for example: http://drupal.org/node/1354#forms So leaving those for now.
Still two more files to go. Hopefully the interdiffs help, although this one is turning out to be a lot smaller than I feared.
Comment #17
xjmThrough form.inc. Not nearly as bad as I thought.
Comment #18
xjmI added a return value to one function here because it was already provided in the multi-line summary that I fixed.
Comment #19
xjmAnd, done.
Theoretically one can just read the interdiffs for a first pass at a review, or to do a partial review. Or, if preferred, one can just read the final patch, which actually didn't turn out to be so terribly big.
Comment #20
aspilicious CreditAttribution: aspilicious commentedNot sure about this one. But why don't we have to use: "Render callback: ..."
Thats everything :)
-9 days to next Drupal core point release.
Comment #21
jhodgdonThat particular doc looks right to me. It isn't a render callback. It's a callback for drupal_map_assoc() and it is documented according to our standards for callbacks.
Comment #22
aspilicious CreditAttribution: aspilicious commentedThan this is rtbc.
Comment #22.0
aspilicious CreditAttribution: aspilicious commentedUpdated issue summary.
Comment #23
xjmStripping a "Paths: " line per #1315992: No standard for documenting menu callbacks.
Comment #24
catch#23: d-g-23.patch queued for re-testing.
Comment #25
jhodgdonThanks for the interdiff! I don't see any other Path items that need removing so yes this is still RTBC.
Comment #26
Dries CreditAttribution: Dries commentedCommitted to 8.x. Moving to 7.x.
Comment #27
xjmLooks like these are the only changes that need to be removed from the backport.
Comment #28
xjmI don't see this commit in D8 yet.
Comment #29
Albert Volkman CreditAttribution: Albert Volkman commentedI see this in D8, do you @xjm? And, D7 backport.
Comment #30
jhodgdonI spot checked a few things from the D8 patch and agree it seems to be there. Thanks for checking and for the d7 backport; needs a review.
Comment #31
xjmBackport looks keen.
Comment #32
xjmWhoops. Sorry @ksenzee.
Comment #33
jhodgdonOne thing needs fixing (errors.inc):
Needs a blank line after the first-line description.
But the rest looked good, so I just patched, fixed this one line, and committed. Thanks!!
Comment #34.0
(not verified) CreditAttribution: commentedUpdated issue summary.
Comment #34.1
xjmUpdated issue summary.
Comment #34.2
xjmUpdated issue summary.