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.
Part of meta-issue #1310084: [meta] API documentation cleanup sprint.
Part of meta-issue #1310084: [meta] API documentation cleanup sprint.
Comments
Comment #1
sven.lauer CreditAttribution: sven.lauer commentedThat was a quick one.
Comment #2
jhodgdonLooks OK... one small thing to fix up:
When referring to a module, either say "Contextual module" or "contextual.module". The latter is somewhat preferred, as it becomes a link on api.drupal.org.
Comment #3
sven.lauer CreditAttribution: sven.lauer commentedRerolling with a fix.
BTW, is this documented somewhere. I've seen the "contextual.module"-type of reference, but I thought this is kind of misleading, given that what one wants to reference is the module itself, not just the .module file.
Comment #4
sven.lauer CreditAttribution: sven.lauer commentedComment #5
jhodgdonTrue about contextual.module referring to the module file itself. In that case, capitalize and use "the": "the Contextual module".
This needs a newline after the @file docblock:
And the word "the", and we're good to go.
Comment #6
jhodgdonRegarding where the convention for modules is documented.... We enforced this convention extensively during the D7 cycle when we overhauled the core modules' hook_help(), and I'm sure we put it in the instructions for how to write a hook_help() (wherever that is...), but it didn't make it to the general writing style guide. So I just added it:
http://drupal.org/style-guide/content#moduleref
Sorry about that!
Oh, here's the standard for hook_help that we wrote, which includes (but does not explicitly state) this standard (the example is from the node module, but we don't really explain the standard):
http://drupal.org/node/632280
Comment #7
sven.lauer CreditAttribution: sven.lauer commentedThis patch just adds the "the".
Comment #8
sven.lauer CreditAttribution: sven.lauer commentedUps, forgot to do a rebase there. Here is the right patch.
Comment #9
xjmIt's a relief to see a short module. :) Looked it over and noticed a few things:
See http://drupal.org/node/1354#callbacks. We don't have a particular standard for Render API yet, but I've used the pattern "Pre-render callback: Foos a bar." for the one-line summaries in #1315886: Clean up API docs for includes directory, files starting with A-C.
Drupal.behaviors.contextualLinks
just needs a verb tense change.Comment #10
sven.lauer CreditAttribution: sven.lauer commentedAgreed on the pre-render callback. I also added an @see contextual_element_info().
Of course, ultimately, the pre-render callback signature should be documented in a single place, and then be removed from this function
I also was not aware that CSS files get docblocks, so I added those.
Comment #11
xjmThere's one bit of trailing whitespace here. Other than that, I think this patch is ready.
Comment #12
sven.lauer CreditAttribution: sven.lauer commentedDarn. I guess I should really add the "kill all trailing whitespace" rule in my editor to js and css files.
Re-rolled version just fixes the whitespace issue in the rtl.css file.
Comment #13
sven.lauer CreditAttribution: sven.lauer commentedA note, looking back over this issue (though it has come up in others, as well): The de facto standard of having a blank line after the @file docblock is not documented, I think. Maybe we should add it to http://drupal.org/node/1354#files ?
Comment #14
sven.lauer CreditAttribution: sven.lauer commentedComment #15
xjmLooks good.
Comment #16
jhodgdonRE #13 - if you do not leave a blank line after the @file docblock, it becomes the docblock for the next thing in the file, which in this case is an (undocumented) variable or function. I don't really think we need to add that to the standards page?
Comment #17
sven.lauer CreditAttribution: sven.lauer commentedHm, okay, so this is not a standard but a fact about the Doxygen implementation / syntax ... which I did not know about (I would have supposed that Doxygen processes the @file directive and hence knows that this applies to the whole file).
http://drupal.org/node/1354 does explain general Doxygen syntax and "pure standards" (I.e. "this is the way we do things"---like the blank line between @param and @return). So it might be a good idea to document this somewhere (Though then again, I suppose it does not come up terribly often outside of cleanup sprints).
Comment #18
jhodgdonOK. I edited node/1354 to make this hopefully a little clearer (both the general section at the top and the file section).
Comment #19
webchickLooks good, seems like this could be backported to D7 as well, minus that "Pre-render callback:" bit.
So, committed and pushed to 8.x (in full) and 7.x (with that hunk reverted).