Consistent style for "@todo" comments

Problem/Motivation

The standard format of @todo statements is agreed. But the documentation pages need updating.

Three supporters required

1. https://www.drupal.org/u/jonathan1055 (18 Nov 2023)
2. https://www.drupal.org/u/{userid} (date added)
3. https://www.drupal.org/u/{userid} (date added)

Proposed changes

1. DocBlock @todo tag api-documentation-and-comment-standards#todo

Current text

The current text is OK, but needs more detail.

Proposed text

Add the following after the first paragraph.

The @todo tag should be in lower case followed by a single space then the text. There should be no : or - between the 'todo' and the following text. Lines may be indented below the @todo

2. Inline @todo comment api-documentation-and-comment-standards#inline

This currently says

@todo statements in inline comments follow the same rules as using the @todo tag in docblocks.

followed by an example. Is this OK as-is? It is good that the rules should only be stated in one place. But for inline comments do we need to say that the @todo must start a new line, not be in the middle of a comment?

Remaining tasks

1. Create this issue in the Coding Standards queue, using the defined template
2. List three supporters
3. Create a Change Record
4. Review by the Coding Standards Committee
5. Coding Standards Committee takes action as required
6. Tagged with 'Needs documentation edits' if Core is not affected
7. Discussed by the Core Committer Committee, if it impacts Drupal Core
8. Documentation updates
   1. Edit all pages
   2. Publish change record
   3. Remove 'Needs documentation edits' tag
9. If applicable, create follow-up issues for PHPCS rules/sniffs changes

For a fuller explanation of these steps see the Coding Standards project page

Original issue

While working on #2719649: Fix 'Drupal.Commenting.InlineComment.SpacingBefore' coding standard, it became apparent that the InlineComment sniff in coder allows TODO paragraphs to be indented if and only if they start with the exact string "@todo ".

Valid example:

    // @todo Lorem ipsum dolor
    //    sit amet.

Invalid examples:

    // @todo: Lorem ipsum dolor
    //    sit amet.

    // @TODO Lorem ipsum dolor
    //    sit amet.

    // @fixme Lorem ipsum dolor
    //    sit amet.

These are rejected because "@todo:", "@TODO" and "@fixme" are not recognized as strings that can start an indented paragraph (see https://git.drupalcode.org/project/coder/-/blob/8.x-3.x/coder_sniffer/Dr...), therefore the second line is considered to be improperly indented. This only affects multi-line @todo comments.

An argument might be made that the rule is too strict and other indented paragraphs should be allowed (some other comments start indented paragraphs with "@see" or even just "Note:"), but what is clear is that core currently mixes several different styles for writing "@todo" comments, and we might want a common style for them. (@todo is only briefly described in the coding standards at https://www.drupal.org/docs/develop/standards/api-documentation-and-comm..., and the style is currently only implicit in the code example).