Many of the API documentation headers in the Drupal Core code base do not conform to our documentation standards (http://drupal.org/node/1354).
The Documentation Team is holding a "sprint" to bring the documentation closer to compliance. To participate:
- Choose an unclaimed module or directory from the Remaining Tasks section below.
- If there is not already an issue there [NOTE: they should already be there now!], file a new issue and assign it to yourself. Issue parameters (you can use this handy link, and then edit the title and assigned fields):
- Project: Drupal Core
- Version: 8.x-dev
- Component: Documentation
- Category: task
- Title: Clean up API docs for [module or directory]
Part of meta-issue [#xxxxx]
- Assigned: Assign it to yourself
- Tags: docs-cleanup-2011, needs backport to D7, Novice
- Edit this issue summary here, and add your issue and user name to the Remaining Tasks section below (or if it was an existing but unassigned issue, just put your user name in the "Assigned" column—and be sure to assign the issue to yourself also).
- As always, when editing an issue summary, you should add a comment to the issue saying what you edited, so that anyone following this issue will get an email. In this case, provide a link to the new issue you filed and state which module/directory you are claiming.
- Make a patch that fixes the following, in each file in your module/directory:
- The file should have a @file documentation block, with an 80-character max one-line summary - see http://drupal.org/node/1354#files
- Each function, method, constant, class, etc. in the file should have a documentation block, starting with a one-sentence, 80-character max, one-line summary.
- Functions/methods one-line summary should start with a verb in the right tense. See http://drupal.org/node/1354#functions, http://drupal.org/node/1354#hooks, and http://drupal.org/node/1354#menu-callback
- There should be a blank line between the @param and @return sections (if any) in documentation blocks.
- @param and @return statements should be formatted correctly (see http://drupal.org/node/1354#functions).
- @see and @ingroup lines should be at the end of the documentation block.
- Lines in docblocks should wrap as close to 80 characters as possible without going over.
- Remove all trailing spaces, e.g. with
perl -pi -e 's, *$,,' $(find core -regex '.*\.\(engine\|html\|inc\|info\|install\|js\|json\|module\|php\|script\|sh\|sql\|test\|txt\|xml\)')
Bonus things that probably need be fixed, but maybe not in this sprint except in small doses (because they make the patches harder to review by the reviewer and the committer -- the items above are all pretty easy to review, since they are fairly mechanical/obvious)... If you find one of these problems in a single function in a file, go ahead and fix it. If you find a lot, file a separate issue and don't include them in your patch.
- All function/method parameters should have @param documentation.
- All functions/methods with return values should have @return documentation.
- Data types on parameters and return values - this is DEFINITELY not part of this sprint. Someone may be organizing a sprint for doing this... for now, don't even file issues on it. Follow issue if interested.
Also, in general, please open separate issues for cleaning up things you notice outside of doxygen blocks or that aren't directly listed above, and refrain from including fixes for them in your patches. We want to reduce as much as possible the collision between these cleanups and other issues. (For a little background on why this is important, see: http://webchick.net/please-stop-eating-baby-kittens.) You can also list other issues you notice under the "Remaining tasks" header of your issue summary.
- Attach the patch to the issue you filed, and set its status to Needs Review. Leave it assigned to yourself, to indicate you will continue working on it if it needs work. Monitor the issue status until it is marked "fixed".
- Start over at the first step if desired!
- If you find that you cannot complete an issue you claimed:
- Add a comment to the issue and un-assign it
- If you have a partial patch, attach it to the issue
- Return here and edit the issue summary - remove your user name from the "Assigned" column to indicate that the issue is available (but leave the link to the issue there). As usual, when editing issue summaries, also add a comment to the issue.
The following modules and/or directories need to be done (see Proposed Resolution steps above). Add issue links and user names to the list as these are assigned. Use this format (after the directory/module name in the list):
- username - [#NNNN], where NNNN is the issue's node ID for the issue you filed. (NOTE: When pasting this into a line below, do not include the "code" tags, or the issues won't turn into nice color-coded links.)
|files in core directory|
|includes directory, files starting with A-C (~14k lines)||xjm|
|includes directory, files starting with D-G*||xjm|
|includes directory, files starting with H-M (~10.5k lines)|
|includes directory, files starting with N-Z (~10k lines)|
|node module||Albert Volkman|
|simpletest base test classes|
|system module (excluding subdirectories)|
|system module, tests subdirectory A-D|
|system module, tests subdirectory E-I|
|system module, tests subdirectory J-Z||mmartinov|
|update module||Tor Arne Thune|
* Except database and filetransfer subdirectories (~9.5k lines)
** Except files subdirectory. We don't want to alter the files in the simpletest/files directory, since they are used in tests
We also need to:
- Figure out specifically which types of changes we're doing in these patches that should and should not be backported to Drupal 7 (see comments 63/64 below).
- Reopen the issues above currently marked "fixed", and mark them for backporting to Drupal 7 instead, with a comment from (a) in them explaining which parts are to be backported.
- Figure out which d7/8 docs standards are not part of Coder, and which can be automatically tested, and file issues in Coder to get them added to the appropriate versions of Coder.