Skip to content

Latest commit

 

History

History
78 lines (70 loc) · 2.86 KB

supported_patters_of_comments.md

File metadata and controls

78 lines (70 loc) · 2.86 KB
Raw

Supported formats and patterns of comments

It detects TODO-tags in single-line comments started with both // and # symbols and multiple-line comments /* ... */ and phpDoc /** ... **/.

  1. Tag and comment separated by colon 
    // TODO: comment summary
  2. Tag and comment does not separated by colon 
    // TODO comment summary
  3. Tag with assignee and comment separated by colon 
    // TODO@assigne: comment summary
  4. Tag with assignee and comment does not separated by colon 
    // TODO@assigne comment summary
  5. Multiline comment with complex description. All lines after the first one with tag MUST have indentation same to the text of the first line. So, all af them will be detected af part of description of TODO. Multiple line comments may have assignee and colon same as single-line comments/. 
    /**
 * TODO: comment summary
 *       and some complex description
 *       which must have indentation same as end of one presented:
 *       - colon
 *       - assignee
 *       - tag
 *       So, all this text will be passed to registrar as description
 *       without not meaning indentations (" *      " in this case).
 * This line (and all after) will not be detected as part (description) of "TODO"
 * case they don't have expected indentation.
 */

As a result of processing of such comments, ID of ISSUE will be injected before comment summary and after colon and assignee when they are presented. For example:

  1. Tag and comment separated by colon 
    // TODO: XX-001 comment summary
  2. Tag and comment does not separated by colon 
    // TODO XX-001 comment summary
  3. Tag with assignee and comment separated by colon 
    // TODO@assigne: XX-001 comment summary
  4. Tag with assignee and comment does not separated by colon 
    // TODO@assigne XX-001 comment summary
  5. Multiline comment with complex description. All lines after the first one with tag MUST have indentation same to the text of the first line. So, all af them will be detected af part of description of TODO. Multiple line comments may have assignee and colon same as single-line comments/. 
    /**
 * TODO: XX-001 comment summary
 *       and some complex description
 */

Assignee-part

It is some "username" which separated of tag by symbol "@". It sticks to pattern /[a-z0-9._-]+/i. System pass it in payload to registrar with aim to be used as "identifier" of assignee in issue tracker.

Compatibility

Script implemented to support formats of "comments with expiration" provided by staabm/phpstan-todo-by. On my point of view, it is cool feature which I'd like to use in my projects.

So, script ignores comments which already have mark of "expiration".