[policy, no patch] Figure out how to document traits and trait methods

Setting up title/tags, as this is a coding standards (or at least documentation standards) decision.

So... Why is it that you think inheritdoc is not the right solution? It seems as though the class has a "use" statement for the trait, so it should be able to inherit the docs for the trait, just like it can for the interface? In theory, anyway.

The API module and/or Grammar Parser will need to be updated for this too, I'll file a separate issue for that.

This is for methods on the actual trait. Not overriding methods. E.g a trait could help implement methods on the interface for the class its included in, using that interface - Not implemented by the trait.

Oh... I see. Obviously, I know very little about Traits. :)

In that case, I think the proposed solution is about all we can do. That will at least link to the method that is being implemented by the trait.

So, here is a proposal for what to put on https://drupal.org/node/1354#classes:

------
- A PHP 5.4 Trait should have an @see reference to any interfaces whose methods it implements in the main trait documentation header block.

 ...
 * @see \Full\Namespaced\Interface\Name
 */
trait MyTraitName {

- The methods of the trait should be documented like this:

/**
 * Implements \Full\Namespaced\Interface\Name::methodName().
 */
 function methodName() { }

----

Something else to consider. We have a standard that all Interface names end with "Interface". Do we need a naming convention for Traits as well, like ending them all in "Trait"?

Incidentally, on #6, it appears that all 3 current issues that are referenced in the parent issue that are proposing new Traits are following this naming convention (ending the name with "Trait"). So it seems that the patch authors think this is a good idea, and we should probably add it to
https://drupal.org/node/608152
as part of this issue.

We probably need an issue summary... done!

I referenced this issue and proposed standard on #2079797: Provide a trait for $this->t() and $this->formatPlural() and was told that the trait being proposed there does not actually implement methods from any interface.

So... We need to think about documentation for that case.

i used the same idea/implementation we had already discussed in #2018411-43: Figure out a nice DX when working with injected translation and onwards

Instead of duplicating documentation in case of just wrapper trait methods just add a
See [namespaced link of parent docs] for details

#9 seems reasonable to me. Updating issue summary accordingly with this proposal.

issue summary looks great to me!

I'm not clear on the use case of point b3 in the issue summary. (Helper method that references out to something else but doesn't fulfill an interface.) Do you have a concrete example?

@Crell: $this->t() is a good example. no point duplicating existing docs of t()

Well t() should also just be a dumb wrapper by now. It would be duplicating the docs of TranslationManager::translate(), no? (Or whatever the method is.)

RE #14 - the docs for how to use t() are still on the t() function, for whatever reason, but that is a separate issue. The point is that the translation trait is a good example of a "trait that is not implementing a particular interface's methods for the benefit of classes to use", so its methods should not be documented in the same way as a "trait that is implementing...".

Ah, I follow now. Rereading that paragraph it makes more sense this time, but I was totally confused by it before. Perhaps restructuring the text to be "If the trait is providing default implementations of an interface, do XYZ. If it's not, do ABC."

Yeah, good point in #16. Slightly tweaked the proposed wording for node/1354 docs in the issue summary.

That reads better, thanks. I made a few language tweaks to help the text flow better. I think it makes sense now.

Hm.... I don't really like the changes you made in #18 -- the language is not parallel now, in the section about how to document methods. Now, the first bullet point says "Trait methods that provide standard implementations for methods from an interface ...", and the second one (which is supposed to be the opposite case) still says "Trait methods that do not implement an interface..."; previously they both used the "implement an interface" language and it was (I think?) clearer that they were opposite cases.

So pick one or the other -- they should use parallel language so it's clear that they are two opposite alternatives. I don't care which wording is used -- just pick whichever wording you prefer and put it on both of those bullet points. Having them worded differently will only lead to confusion.

might be offtopic here:

do we need to add a note as well, for when using multiple traits in a class, that they should be separated by a newline?

eg see #1289536-263: Switch Watchdog to a PSR-3 logging framework point 8

Maybe we should expand this thread to account for everything about traits not just the methods?

#20 is currently off-topic, since this issue is about naming and documentation only, but if there are other standards to discuss, we could broaden it... but that #8 item in that comment on the other issue seems just like regular coding standards, not specific to traits (about whether there should or shouldn't be a blank line at the beginning of a class body).

I've opened a thread on the PHP-FIG list to discuss this as part of PSR-5, as well: https://groups.google.com/forum/#!msg/php-fig/hhcTJp6aWWI/dD2Mt_J5JC4J

Coding standards decisions are now supposed to be made by the TWG

Moving this issue to the Coding Standards queue per the new workflow defined in #2428153: Create and document a process for updating coding standards.

I think #20 is out of scope here, as this issue is specifically traits and their methods, not places where a trait is used.

(Tweaking the title, as the issue summary's proposal is about the documentation on the trait as a whole as well as the trait's methods.)

+1 from me, all looks good.