Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
Problem/Motivation
Part of meta-issue #1310084: [meta] API documentation cleanup sprint
Proposed resolution
Correct the following in the Test base classes in core Simpletest module:
- 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
Patch needs to be rolled.
User interface changes
None.
API changes
None.
Follow-up issues
None.
Comment | File | Size | Author |
---|---|---|---|
#1 | 1805264-1-testbase-docs.patch | 84.22 KB | Lars Toomre |
Comments
Comment #1
Lars Toomre CreditAttribution: Lars Toomre commentedThere is much clean up required to make the Test base classes in the Simpletest module conform with D8 documentation standards. Examples include:
Where I was uncertain of a value or string, I used '???' to indicate that something needs to be supplied before this patch can be committed. Let's see what the bot thinks of this untested first patch for this issue.
Comment #2
jhodgdonPlease confine this patch to API documentation -- no code lines. Thanks!
Aside from that, most of the patch looks good! A few things to fix up:
a)
Wrapping -- this can all go on one line.
b) Maybe this information should be left in the first line (if it fits):
Same with the following function... Having it in the first line will help when scanning the method list. If you do need to move it, at least make the capitalization consistent ('not FALSE').
c)
Let's leave these changes out for now. There's a separate issue that's discussing wholesale changes to how the $message/$group parameters should be documented so it would be better to do it there:
#1457320: Document that t() should not be used for assertion message texts and groups
d)
Backup is not a verb. It should be "backs up".
e)
Should only be one space after . in this line. There's another one at
f)
Needs one-line summary.
g)
There is a verb tense agreement problem in the new paragraph (is/was). The same problem is in the next few doc blocks.
h) Take care of the ??? in the patch.
That's about where I lost steam... it looks like this patch isn't done.
Comment #3
Lars Toomre CreditAttribution: Lars Toomre commentedMoving to simpletest component because although it primarily is a documentation patch, the patch in #2 attempts to bring some rationalization to use statements at top of the three base test files. Apparently changing code and documentation in the same patch is inappropriate for a documentation patch.
Comment #4
jhodgdonUm. We need a docs cleanup patch for the API Docs Cleanup effort. Please just provide a patch that doesn't mess with code. Thanks!
Comment #5
Lars Toomre CreditAttribution: Lars Toomre commentedI will leave it to someone else to roll such a patch.
Comment #6
jhodgdonThese issues are a lot of work with very little tangible payoff, so I'm closing the rest of them as "won't fix". Your efforts on working on this issue were appreciated... it was just my fault for starting a task that was very difficult to get right.
Let's instead put our effort into fixing and reviewing documentation that is really unclear and/or wrong, and I hope that the people who worked on these issues are not afraid to jump into a more reasonable issue!