On Thu, May 17, 2012 at 10:01 PM, David E. Wheeler
<[email protected]> wrote:
> On May 17, 2012, at 11:18 PM, Marvin Humphrey wrote:
>> Perhaps we should consider reStructuredText as an alternative.
>
> That might be okay, though it is not as nice as Markdown in plain text.
reStructuredText is probably a little noisier to read, true. But at least
they're both quite readable in comparison to HTML, or XML as used in C#
comments:
http://broadcast.oreilly.com/2010/06/understanding-c-xml-comments.html
/// <summary>
/// The constructor sets the name, age and cash
/// </summary>
/// <param name="name">The name of the guy</param>
/// <param name="age">The guy's age</param>
/// <param name="cash">The amount of cash the guy starts with</param>
public Guy(string name, int age, int cash) {
this.name = name;
this.age = age;
Cash = cash;
}
>> A DocuComment has two sections.
>>
>> body
>> Description, formatted in Markdown. The first sentence must be a
>> summary that can stand on its own. Terminated by the first line
>> which begins with an "@" character or by the end of the comment.
>>
>> tags
>> The comment may end with an optional tags block. Each tag begins
>> with a supported @label at the beginning of a line, and is
>> terminated by either the next tag or the end of the comment.
>
> Is this ReST? I don't recognize it as Markdown.
Haha, it's neither. It's an actual proposal, formatted as plain text. I tried
to make it look like a definition list to please you. :)
> As I said, I am unfamiliar with the @param syntax. Is it part of Sundown?
Those @tags, including @param, @return, etc, are a convention used in Javadoc,
Scaladoc, Doxygen, and others.
http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#param
https://wiki.scala-lang.org/display/SW/Tags+and+Annotations
http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam
The idea is to treat the comment as an object which has properties, rather
than as a single blob of markup. That gives downstream renderers more choices
for output. For example, we might choose to output each @param tag as a
bullet list, or as a definition list.
It's a powerful and elegant system -- but arguably another extension to
Markdown, if you want to see it that way.
However, there's more than one way to specify properties, as the C# XML system
illustrates -- @tags are great, but it's not mandatory that we use that
particular syntax.
In reStructuredText, I think we can use "field lists":
http://docutils.sourceforge.net/docs/user/rst/quickref.html#field-lists
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists
Example:
:param foo: A Foo.
:param bar: A Bar.
:return: true on success, false on failure.
> http://www.justatheory.com/computers/markup/markdown-table-rfc.html
For giggles, here's a version of your table example in reStructuredText:
http://rst.ninjs.org/?n=4e1d41f32466afe278bd69c310d12cf1&theme=basic
+------+-------------+------------------------------+--------+
| id | name | description | price |
+======+=============+==============================+========+
| 1 | gizmo | Takes care of the doohickies | 1.99 |
+------+-------------+------------------------------+--------+
| 2 | doodad | Collects *gizmos* | 23.80 |
+------+-------------+------------------------------+--------+
| 10 | dojigger | Handles: | 102.98 |
| | | | |
| | | * gizmos | |
| | | * doodads | |
| | | * thingamobobs | |
+------+-------------+------------------------------+--------+
| 1024 | thingamabob | Self-explanatory, no? | 0.99 |
+------+-------------+------------------------------+--------+
> But of course, no table or definition list proposal (I had one of those,
> too) has been accepted.
reStructuredText has definition lists, too, FTR.
http://docutils.sourceforge.net/docs/user/rst/quickref.html#definition-lists
Marvin Humphrey
