Parse Multiline Todos

[matthewwithanm]

If you're using a linter to limit line length, you can easily end up breaking up a single TODO into multiple lines. It would be awesome if that would be recognized and the full TODO text shown.

[jamischarles]

hm... This is tricky... What would you use as a delimiter to tell from legit comments (as a continuation) vs code on the next line?

[matthewwithanm]

I would've assumed a blank line, but I could see how some people might expect that to be a new comment. Another option would be to check indentation:

// TODO: this is a todo that just so happens to be long enough to wrap to the
//       next line.

[jamischarles]

I accept PR's :). I'd like to add a bunch of test cases for this to be more stable. At that point testing scenarios like this will be much easier.

[jamischarles]

Is this a common use case? Anybody else want this?

[matthewwithanm]

Sorry, I've been super busy lately but this is definitely still on my radar. (Maybe I write more detailed TODOs than most though.)

[jschroeder9000]

I would also find this useful as I also tend to have a couple of lines for TODOs. I vote for blank line as delimiter, but also any line that doesn't start with a comment (sans leading whitespace).

E.g.

# TODO improve needs_improvement function
# details about improvements to make
def needs_improvement # this really needs improvement
  ...
end

So in the above example, the first two lines constitute a multi-line TODO and everything else is irrelevant.

[jamischarles]

Two questions as we explore this:

1. Does atom have a language agnostic way to tell us if something is a comment?
2. Is the point of using TODO-show to give you a marker and say "hey, you have a FIXME here, and this is a preview of what it says"? Or is it to be a full copy of the comment? I have been using it for the prior. Thoughts?

[jschroeder9000]

1. https://atom.io/docs/api/v0.136.0/TextEditor#instance-isBufferRowCommented It's not clear to me how/if this can be used in the context of this package.

2. In its current state it is the former (unless you use a really long single-line comment with no follow up lines). If the proposed functionality is implemented, it would/could become the latter.

I think a neat approach (assuming this is realistically doable) would be to display the TODOs as an accordion. In a collapsed state it would show just the line containing the TODO and in an expanded state it would show the subsequent lines. Maybe an option could be added to default to a collapsed or expanded state. This way it could be used as either (or both).

[1j01]

There's also the case of non-start-of-line comments, in which case following comments are probably not intended as a continuation of the TODO, although it is possible.

def needs_improvement # TODO: improve this
  # Set up the things
  ...
  # Do the things
  ...
end

[barrymieny]

The Ruby Style Guide recommends indentation for multiple lines:

If multiple lines are required to describe the problem, subsequent lines should be indented three spaces after the # (one general plus two for indentation purpose)

[suark]

What if people had to do TODO<number>:

// TODO1: This is line one of todo 1    
// TODO1: This is line two of todo 1

So if it already detects a TODO by the string "TODO" then it would parse that and if a number comes between the 'O' and the ':' then it would assume that anything else that matches, would be part of the same TODO?

[1j01]

@suark If it came down to syntax that you have to follow, \ at EOL would be simpler.

[mrodalgaard]

I do not think these EOL markers or weird start syntaxes will ever be naturally used by developers writing todos in a hurry. If there were a bulletproof way of parsing these multiline todos, without adding magic characters, I would consider adding this feature. I would probably not use it myself, because I believe todos should be concise and extra notes should be added elsewhere.

Take a look point 2 of at what @jamischarles originally wrote #13 (comment).

[casdevs]

others use indentation to do multiline TODOs, e.g. please see
https://www.jetbrains.com/help/idea/using-todo.html
intellij-rust/intellij-rust#3130