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.
There's a bunch of documentation that needs to happen. The discovery interface doesn't even have any. :(
This is a meta issue to track people trying to help document things.
Comment | File | Size | Author |
---|---|---|---|
#12 | plugins-docs-1512588-11.patch | 1.56 KB | effulgentsia |
#11 | plugins-docs-1512588-11.patch | 0 bytes | effulgentsia |
#9 | interdiff.txt | 8.8 KB | neclimdul |
Comments
Comment #1
neclimdulComment #2
cosmicdreams CreditAttribution: cosmicdreams commentedCan I help in this effort even though I don't have intimate knowledge of the code? Are there any simple tasks that need completed?
Comment #3
effulgentsia CreditAttribution: effulgentsia commentedUpping to critical, because there's no way the system can be committed to core without decent documentation.
@cosmicdreams: thanks for the offer. I don't know yet, but will post ideas on how to proceed once I have them. Maybe neclimdul or someone else with intimate knowledge will post their ideas here as well.
Comment #4
effulgentsia CreditAttribution: effulgentsia commentedSome of the work here might benefit from us first refining some terminology in #1560138: Refine terminology ?. Adding the link here so people can go "follow" that issue.
Comment #5
neclimdulIt might. Its mostly what to call the meta data that defines a plugin implementation and what to call the string that identifies it.
The docs have gotten a lot better since I posted this but we might take a quick pass and see how much of any code is missing docblocks or param types which I know I am sometimes lazy about. It'd be great if we can do a good job on this but there are people in the core queue that are very good at reviewing these sorts fo things so we can lean on that some too.
Comment #6
neclimdulthe docs review we needed to kick this off. http://drupal.org/node/1497366#comment-6078154
Novice because I think a lot of those can probably be knocked out without a deep understanding of all the crazy things plugins are doing. Feel free to ping me on irc if you have concept questions ;)
Comment #7
Niklas Fiekas CreditAttribution: Niklas Fiekas commentedMoving things over here, as sun suggested:
I've been going backwards through the patch, superficially looking for coding style issues, to get a first idea of what this does. Thanks all! This looks pretty good.
Except some docblocks that are already marked with todos I've noticed these nitpicky things:
:)
Should have a short description instead.
This needs to have an @file, and should be seperated from the namespace statement with a newline.
This class should have a docblock.
Not sure what this means for us, here.
:)
This file needs a doc block ala "Defintion of x."
This class should have a docblock.
This method should have a short docblock.
This method should have a short docblock.
This method should have a short docblock.
This method should have a short docblock.
This method should have a docblock.
This method should have a short description doc block, saying "Tests xyz.".
This file needs a docblock, like "Defintion of ...".
This class needs a docblock.
Is this still nescessary? If yes, maybe add @todo, so that we find this later.
This file needs a docblock.
This class should have a docblock. Btw. with the name
DeriavativeTest
this looks like a test case on the first glance.Superflous empty line.
Put a newline between these?
This class should have a docblock.
We usually have a newline between namespace and use, but not between use statements.
This class should have a docblock.
Comment #8
neclimdulCommitted and pushed some doc cleanups from eclipse #1497366-79: Introduce Plugin System to Core and some of my own. A number(but probably not all) of these where addressed.
Comment #9
neclimdulrelevant, the interdiff of eclipse's patch.
Comment #10
effulgentsia CreditAttribution: effulgentsia commentedYep, what's left to do from #7 is improving PHPDoc for the classes: Drupal\Core\Cache\Cache, Drupal\image\Effect, Drupal\system\Tests\Plugin\*, and Drupal\plugin_test\*.
Comment #11
effulgentsia CreditAttribution: effulgentsia commentedThis includes simple docs for Drupal\Core\Cache\Cache and Drupal\image\Effect. Leaving at "needs work" for test classes. Any volunteers?
Comment #12
effulgentsia CreditAttribution: effulgentsia commentedAhem. Let's try again.
Comment #13
neclimdulLooks good. Keep em coming! :)
Comment #14
effulgentsia CreditAttribution: effulgentsia commented#12 was committed. I think test docs are complete in #1638050: Provide real world values for derivative test. So, marking this issue fixed.
Comment #15
neclimdulI see a number of @todo's for docs in the DefaultFactory and DefaultMapper after the patch so going to leave this open still.
Comment #16
effulgentsia CreditAttribution: effulgentsia commentedNo more todos in plugins-next!!