lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David E. Wheeler" <da...@justatheory.com>
Subject Re: [lucy-dev] Markdown for documentation
Date Fri, 18 May 2012 18:57:39 GMT
On May 18, 2012, at 2:40 PM, Marvin Humphrey wrote:

> 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;
>     }

I am glad you don’t hate the rest of us enough to do something like that. ;-P

>> 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.

Ah, I see. Never used them. You would have to extend the parser to use them.

> 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.

Since it is not a part of Markdown, I have trouble seeing how it could be considered anything
else.

> 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.

I guess that would work.

>>  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 |
>    +------+-------------+------------------------------+--------+

Very MySQL-y.

>> 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

Those look pretty good.

Best,

David



Mime
View raw message