Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
Part of meta-issue #1310084: [meta] API documentation cleanup sprint and continuation of #1327484: Clean up API docs for book.
This issue is focused on further changes to bring Book module closer to D8/D7 documentation standards. This issue, for instance, will ensure that there are no missing @param or @return directives from docblocks and that the various Test files are in accord with http://drupal.org/node/1354. There also appears to be at least one missing @file directive.
Comment | File | Size | Author |
---|---|---|---|
#7 | book_docs-1807688-5.patch | 11.29 KB | Albert Volkman |
#5 | 1807688-5-book-docs.patch | 13.32 KB | Albert Volkman |
#5 | interdiff.txt | 4.44 KB | Albert Volkman |
#3 | 1807688-3-book-docs.patch | 15.45 KB | Lars Toomre |
#1 | 1807688-1-book-docs.patch | 922 bytes | Lars Toomre |
Comments
Comment #1
Lars Toomre CreditAttribution: Lars Toomre commentedAttached is a small patch from starting to perform a full review of the Book module for compliance with D8 documentation standards.
If interested, please add to this patch as one does a full review of each of the files in the Book module directory.
Comment #2
jhodgdonThis patch has no problems, so I committed it to 8.x and the .js file part to 7.x (the css file does not exist there). Thanks! Leaving open for further work if necessary.
Comment #3
Lars Toomre CreditAttribution: Lars Toomre commentedHere is a patch that contains changes from doing a full review of the Book module (including its Test class).
Comment #4
jhodgdonThanks, most of this looks good! A few updates needed:
a) In book.admin.inc:
Needs . at end of line.
b) in book.install:
Only capitalize Book in "the Book module". I guess here it should say "Move Book module settings...". Also check other capitalization changes, such as in the BookTest.php file.
d) book.module
By convention we do not include return value docs for hook_menu access callbacks (there are 3 in this patch).
e) book.module
- children got left out - was that intentional?
f) BookTest.php
Nodes should not be capitalized in the @param description? And the @return docs don't actually tell me what the regexp is for -- and of course it's a string (that is how regexps are in PHP), so that's not useful information.
g)_ same file
id -> ID
Comment #5
Albert Volkman CreditAttribution: Albert Volkman commentedAddressed issue raised in #4 and found a few others.
Comment #6
jhodgdonThanks! This one looks good, and I committed it to 8.x. I guess we should port it to 7.x -- careful though, as there are references to the Node class etc. which don't exist in 7.x.
Comment #7
Albert Volkman CreditAttribution: Albert Volkman commentedComment #8
jhodgdonLooks good to me! I'll get it committed soon. (Only one pass on this one -- great!)
Comment #9
jhodgdonIt's in -- thanks!