I'm running into this particular confusion rather a lot while writing Docco-parallel-annotated code. It's probably best illustrated through example:
# We're going to do something that involves a couple of steps now, which will
# be useful in the long run because of blah and foo. There are several lines of
# description of the thing-we-are-about-to-do in general here.
# This is specific documentation for the first step of the thing that we are
# doing that explains why we are doing that first step in the way we are doing
Now, I'd like for the code snippet to be aligned with the second paragraph, the one that most directly pertains to it. However, the code always appears next to the earliest paragraph that precedes it.
I can get it looking alright by doing this:
# This is the documentation for the previous piece of code that's unrelated to
# the next bit.
# This is the general description of the next bit. It does not really belong
# here; it should be after the next line, but if it put down there Docco will
# line up this general description with the specific first step and it will be
# more confusing.
# This is specific documentation for the first step of the thing we are doing.
However, this is obviously a crude hack, and it royally messes up if you view the code using Docco's linear layout instead.
Is there some way to notify Docco that a given line of code should adhere to a particular paragraph, instead of always the earliest paragraph that directly precedes it?
That's a really good question. I think that the current behavior is the desired behavior most of the time ... but there's certainly times when you have this case as well. It would be nice if we could have a simple heuristic that distinguishes between the two.
Hmm. Is it possible for Docco to treat a totally empty line (or one with just whitespace) as an code section (containing the empty string of code)? Then you'd still get the current behaviour like this:
# This is the first paragraph of description for the following line, blah blah
# blah etcetera.
# This is a second paragraph. The code should appear next to the first
# paragraph and not this one.
And you could use "introductory" paragraphs by doing this:
# This is an introductory paragraph that explains the junk we're gonna do in
# this part of the code in detail.
# This is a paragraph of information about the first snippet of code; the
# following code snippet will align with this paragraph, not the previous one.
This allows for both styles fairly easily, and is in my opinion reasonably clear. Thoughts?
Ooh, I like it.
Allows blank lines to be counted as code fragments, addresses #189
This makes it possible to have adjacent blocks of comments where the later
block is directly related to the following snippet; examples are given in #189.
That change pretty much addresses my issue, so this can be closed now.