Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
Problem/Motivation
There are several small problems with the FlagServiceInterface documentation. Classes aren't fully namespaced. Only brief descriptions are provided. In general, the documentation needs a bit of love.
Proposed resolution
Update and expand the documentation for FlagServiceInterface.
Remaining tasks
Create, test patch.
User interface changes
None.
API changes
Only documentation changes.
Comment | File | Size | Author |
---|---|---|---|
#8 | 2482577.8.flagServiceDocsLove.patch | 5.69 KB | socketwench |
| |||
#6 | 2482577.6.flagServiceDocsLove.patch | 1.92 KB | martin107 |
| |||
#5 | 2482577.5.flagServiceDocsLove.patch | 636 bytes | martin107 |
| |||
#2 | 2482577.2.flagServiceDocsLove.patch | 4.94 KB | socketwench |
Comments
Comment #1
socketwench CreditAttribution: socketwench commentedComment #2
socketwench CreditAttribution: socketwench commentedMoving Martin's patch from #2476499: Give the documentation of the flag count API some love. to here...
Comment #3
joachim CreditAttribution: joachim commentedLooks good to me.
Is any further work needed here, or should this be committed?
Comment #4
socketwench CreditAttribution: socketwench commentedI think the methods could use further description and examples.
Comment #5
martin107 CreditAttribution: martin107 commentedOther patches have been improving the dockBlocks
Instead of rerolling, it is better to restart with a much smaller patch - only the FlagServiceInterface::unflag() param tags need FQDNames
The descriptions have been updated in the meantime - so the work that remains is a light sprinkling of examples.
Comment #6
martin107 CreditAttribution: martin107 commentedIt is difficult to provide anything more than a trivial example for FlagServiceInterface::flag() without inserting code snippet the size of "War & Peace".
To criticize by own work ... hmm If I were looking for code example my instinct would not be to look in the dockBlock for flag()
So it is the opposite of discoverable.
So this is a question for review.... Should I move the code example? Perhaps Readme.md ?
Comment #7
joachim CreditAttribution: joachim commentedI wouldn't put developer docs that are fairly detailed in README. If anything, that level of detail should go in docs pages on d.org (which are a mess at the moment, and still waiting for the tools to make them not be a mess).
If anything, our services are a main part of our API, so docs there are fine. Though I'm not sure we need to recap how to create a node programmatically -- if anything, that's an extra maintenance burden, as it's not our code we're demonstrating.
Comment #8
socketwench CreditAttribution: socketwench commentedI think we need to avoid "create the universe first" examples. We can cut those down by assuming that the nodes/flags/etc. already exist and reference the appropriate load() methods. Then, the reader would have a searchable reference elsewhere in Drupal docs to put together the bigger picture.
Even so, I still think we should keep the example about how to programmatically create a Flag! Let's just move it to FlagInterface where it'll be more useful.
Here's some off-the-cuff examples for the rest of the FlagServiceInterface. We will need to tweak the wording a bit more, I think.
Comment #9
martin107 CreditAttribution: martin107 commentedThanks for the constructive criticism ...
https://www.drupal.org/node/2126285
That goes through lots of my concerns.
Using the appropriate load and moving stuff into FlagInterface ...it is a good idea.
All the changes in #8 look perfect ... thanks for showing me how it is done.
socketwench++
Comment #11
socketwench CreditAttribution: socketwench commentedThanks everyone!