lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marvin Humphrey <mar...@rectangular.com>
Subject Re: [lucy-dev] Markdown for documentation
Date Fri, 18 May 2012 18:40:12 GMT
On Thu, May 17, 2012 at 10:01 PM, David E. Wheeler
<david@justatheory.com> 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

Mime
View raw message