Closed mathieupinet closed 8 years ago
will pill says:
would be good to clarify what we must/should do for return types that are arrays of arrays or arrays of mixed types also, can
return Type[]
return an empty array?
Fine with me. Should share it around to get feedback from others.
Would also be good to adapt our code sniffer standard to pickup this stuff as much as possible: https://github.com/graze/graze-standards/blob/master/PHP/CodeSniffer/Graze/ruleset.xml
Writing custom sniffs is pretty easy.
Needs some links to what tags are actually valid (how about this?), and what are required on a method.
I'd assume param
, returns
, throws
, what else?
What about {@inheritDoc}
usage?
I'd say we should recommend having a distinction between a short and long description on a method, kinda like git.
What about the formatting of the (long) description? I'm cool with markdown, but maybe tools better support html.
@sjparkinson @return
and @param
are the only required ones, isn't it clear from https://github.com/graze/standards/pull/21/files#diff-04c6e90faac2675aa89e2176d2eec7d8R66 ?
@sjparkinson thinking about @inheritdoc
(and learning that it only really inherits the description) led me to this thought: should classes that inherit the exact same documentation even HAVE a DocBlock?
I've been thinking about @inheritdoc
and I'm currently thinking that we shouldn't use it and we should explicitly define the doc block for sub-methods.
@sjparkinson I haven't come across methods with a description verbose enough that I had to consider a special format for it. Is it an issue in our Open Source projects?
@sjparkinson @return and @param are the only required ones, isn't it clear from https://github.com/graze/standards/pull/21/files#diff-04c6e90faac2675aa89e2176d2eec7d8R66 ?
Yes, after re-reading it. Being totally honest I found a lot of these verbose and just skimmed them.
@sjparkinson thinking about @inheritdoc (and learning that it only really inherits the description) led me to this thought: should classes that inherit the exact same documentation even HAVE a DocBlock?
Yes, return values can change, and I've never seen otherwise elsewhere.
@sjparkinson I haven't come across methods with a description verbose enough that I had to consider a special format for it. Is it an issue in our Open Source projects?
Something to consider another time.
@sjparkinson @wpillar : just realised this was still unmerged, are there pending issues?
Closed to create a new PR as #25.
New standards: