Block document constants

[rhavin]

see this code-snipped:

# ansi console color constants
COLOR_BLACK = 0
COLOR_RED = 1
COLOR_GREEN = 2
COLOR_YELLOW = 3
COLOR_BLUE = 4
COLOR_MAGENTA = 5
COLOR_CYAN = 6
COLOR_WHITE = 7

# functional color aliases
COLOR_WARN = COLOR_YELLOW
COLOR_ALERT = COLOR_RED
COLOR_CONFIRM = COLOR_GREEN
COLOR_NOTE = COLOR_BLUE

I dont see any use in putting an explanation above each constant, but they still should get documented. Is (or shouldnt?) there any syntax for constant-blocks that're going to get documented any used by including classes?

perhaps something like…

# some descriptive text
CONST_1 = 1
CONST_2 = 2 (…)
#^         <- mark block-end

…?

[drbrain]

If you're concerned about your "documentation coverage" number, don't be. It's purely for amusement purposes, especially when you have self-documenting constants like this.

What documentation would you like to see for these constants?

I think you might be looking for sections: http://rdoc.rubyforge.org/RDoc/Markup.html#label-sections

You can use the :category: or :section: to group methods, constants or attributes in a useful manner like this:

# :section: Colors
#
# These are the ANSI color constants

COLOR_BLACK = 0
[…]

# :section: Color Aliases
#
# These are functional aliases for the ANSI color constants
COLOR_WARN = COLOR_YELLOW
[…]

# :section:

The last :section: resets to the default section.

You can see an example of section display at: http://rdoc.rubyforge.org/RDoc/Markup/ToHtml.html

[rhavin]

Thanxfor answering, but its not a satisfying solution. The "documentation coverage" number is much more than an amusement – it's a very useful and often contract relevant feature. The usual agreement states 100% documentation, and what's really needed is some :switch: that simply states: The mere constant enlistment is the documentation… something like…

  # :constlist: ansi console color constants
  COLOR_BLACK = 0
  COLOR_RED = 1
  COLOR_GREEN = 2
  COLOR_YELLOW = 3
  COLOR_BLUE = 4
  COLOR_MAGENTA = 5
  COLOR_CYAN = 6
  COLOR_WHITE = 7
  # :constlist:

…perhaps, that gets rendered as:

ansi console color constants COLOR_BLACK (0) COLOR_RED (1) COLOR_GREEN (2) COLOR_YELLOW (3) COLOR_BLUE (4) COLOR_MAGENTA (5) COLOR_CYAN (6) COLOR_WHITE (7)

…would be nice.

[drbrain]

I'll see what I can do, but I may not be able to add it to RDoc 4.0 as my time is limited.

I think I can make this work by putting the constants in a section (internally) using a separate directive that also marks them as documented for the purposes of the coverage report.