mojombo/tomdoc — Issue #27: Making TomDoc play nicely with code folding
Author: RichMorin
Created: 2011-10-13 17:57:08+00:00
State: open

Like many documentation formats, TomDoc does not play nicely with the code-folding support found in editors such as TextMate. Specifically, although the editors allow code folding, they don't fold the TomDoc blocks (which may well be longer than the code itself).

Although this problem _could_ be addressed by reworking each editor, this seems infeasible. So, I suggest a slight opening up of TomDoc's syntax.

Consider your example code (multiplex), as listed on

http://tom.preston-werner.com/2010/05/11/tomdoc-reasonable-ruby-documentation.html

Using code folding, I can turn the method's three lines of code into a single line. Unfortunately, this leaves me with 11 lines of unfoldable commentary. A typical code file might have dozens of methods, each of which might have dozens of lines of header comments. How am I supposed to view only the lines of interest?

In my own code, I've developed two workarounds for this problem: comment methods and internal comment blocks:

* Comment methods handle the problem of documenting classes and methods. They are simply "do-nothing" methods with internal comment blocks, as described below. I use the name `header_comment` for these, but any mnemonic name would serve.

* Internal comment blocks differ from current TomDoc format only slightly. Because they are located inside the method being discussed, they get folded along with the code.

```ruby
class A_Class

def header_comment
#
# ... TomDoc comment text ...
end

def a_method
#
# ... TomDoc comment text ...

... code ...
end

end
```

In TextMate, this folds down to:

```ruby
class A_Class

def header_comment ooo

def a_method ooo

end
```

Would you accept an extension to TomDoc to support this syntax? Alternatively, is there a cleaner solution?