Based on API documentation and comment standards
we can read that:
- All summaries (first lines of docblocks) must be under 80 characters, start with a capital letter, and end with a period (.).
- One-line summary, ending in a period (.).
plus the logic of Coder where it adds period on every inline comment, see:
- #2742881: Can inline comments end with semicolons
- #2607574: Don't add dot with inline comments containing code with semicolon
Following above logic, does it mean the page about coding standards doesn't following these standards?
Page: API documentation and comment standards
Example 1:
// @todo Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
// nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
// sed diam voluptua.
Example 2:
// Sample code here
Example 3:
// Note: especially in Drupal 8, these callback implementations may be
// class methods rather than functions, which are passed in as PHP
// callables rather than strings. So an alternate wording that
// implies that this is also acceptable would be:
If so, should these examples be fixed? And documentation clarified when we should use periods at the end of the lines for inline comments?
Comments
Comment #2
kenorb CreditAttribution: kenorb commentedComment #3
kenorb CreditAttribution: kenorb commentedComment #4
drunken monkeyBoth of the sentences you cite are referring to just the first line of a doc comment – that is, the
structure that should go before every class, method, function, constant and property.
Inline comments are just restricted by this:
Your second example still violates that (and there is discussion about ending a comment with a colon, but there's already an issue discussing this), but I'd argue that it's just a placeholder, not a real example of a comment.
Comment #5
borisson_I agree with @drunken monkey, we also discussed this during the latest coding standards meeting in slack. Closing this issue.