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

kenorb created an issue. See original summary.

kenorb’s picture

Issue summary: View changes
kenorb’s picture

Issue summary: View changes
drunken monkey’s picture

Both 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:

All documentation and comments should form proper sentences […]

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.

borisson_’s picture

Status: Active » Closed (works as designed)

I agree with @drunken monkey, we also discussed this during the latest coding standards meeting in slack. Closing this issue.