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
Core is full of interface documentation like "TypedConfigManagerInterface: Defines an interface for typed configuration manager". That's not particularly useful. Some interfaces do not have a doxygen at all. The attached file lists all the interfaces in Drupal\Core and Drupal\Component together with the doxygen length. It's... not pretty.
Proposed resolution
Write doxygen.
Remaining tasks
Write doxygen.
https://docs.google.com/spreadsheets/d/1R0DPvI2u7q1u-sWWaeELRDbTjXB0b7U7...
| Comment | File | Size | Author |
|---|---|---|---|
| interfaces.txt | 14.92 KB | chx |
Comments
Comment #1
jhodgdonSounds like the next step on this one would be to go through the interfaces and figure out which ones really need more docs or are totally inaccurate, and which ones are probably OK.
For instance, it's possible that an interface called Drupal\Core\Mail\MailManagerInterface could have docs like "Defines an interface for managing mail" and that would probably be sufficient, but on the other hand, some interfaces have no docs and some of them are for things that people don't generally know about (like Typed Data or Typed Config) and should at least have an @see to a topic that explains what they are.
Comment #2
chx CreditAttribution: chx commentedI am totally on it.
Comment #3
rmenes379 CreditAttribution: rmenes379 as a volunteer commentedI can help clean this up if needed.
Comment #4
webchickMore accurate and less aggro title.
Comment #5
xjmEven less aggro, since the previous one still got my back up. :P
Comment #6
chx CreditAttribution: chx commentedComment #7
chx CreditAttribution: chx commentedSeriously: I need education here. The doxygens in question literally gives us no information that's not in the interface name. Very often they are the same except some small words (for, a etc). So: they are useless. Why calling them useless is aggro?
Comment #8
jhodgdonI agree with chx here... The original issue title of "Most interface documentation is useless" ***was actually accurate***. Take a look at the docs (prior to the couple of patches that chx has already made)... As was pointed out in #7 and earlier:
- Some interfaces don't even have a doc block
- Some are completely inaccurate (copy/pasted from a different interface and never edited)
- Most of the rest just basically repeat the name of the class.
- Only a few actually give you information that you could use.
How is that not "most interface documentation is useless"?
On the other hand, the issue title was rather blunt, and there are always more diplomatic ways to point out that Drupal has problems (like making a more bland title but marking the issue Major and Bug, which tends to make people say "fair enough" rather than rushing to soften the blow).
Anyway... I was also annoyed and sad that people felt the accurate title was aggressive and that they had to retitle the issue -- which now sounds like it's a task that affects few interfaces (which is not accurate) rather than a major bug (which is accurate). But I just let it go. Let's get back to the work of fixing the problems and move on.
[Note: I was going to rant a lot more here, but I deleted the rest.]
Comment #9
dawehnerWell we could make that explicit: Too many interfaces doxygen are insufficent
Comment #10
jhodgdonOr we could stop discussing the issue title and just get back to actually fixing the problems ;)
Comment #11
chx CreditAttribution: chx commentedI got this pointer: http://xjmdrupal.org/blog/someone-worked-hard-on-it
Comment #12
ifrikI'm not quite clear about the issue description: Is it about interface text?
If so, can we take it up during the sprints at DrupalCon Barcelona, as part of an effort to improve UI text?
Comment #13
cilefen CreditAttribution: cilefen commentedThis is a meta issue about improving doxygen documentation on object interfaces. It is nothing to do with UI text.
Comment #15
chx CreditAttribution: chx commentedComment #25
quietone CreditAttribution: quietone at PreviousNext commentedAll the child issue have been fixed, so time to close this meta.
Work on improving documentation is ongoing. Anyone wanting to focus on this are can join Drupal slack #documentation.
Thanks