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 Wed, 23 May 2012 16:58:06 GMT
On Fri, May 18, 2012 at 11:57 AM, David E. Wheeler
<david@justatheory.com> wrote:

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

I don't think anyone who is familiar with Javadoc/Scaladoc/Doxygen would see
it that way -- the format would be perceived as "Javadoc with Markdown",
rather than "Markdown with @tags".  And of course, that's by design -- it
would be advantageous to leverage existing developer familiarity with Javadoc.

However, the *feature* we are trying to support here is document metadata, and
@tags are only one way to specify metadata.  With the proper parser, we could
also extract metadata from definition lists using something similar to the
syntax you propose here:

  http://www.justatheory.com/computers/markup/modest-markdown-proposal.html

For example:

    /*| Do stuff with `foo` and `bar`.
      |
      | Wrangle `foo` into a consumptive form after mutating its `okra`
      | component from `ok` to `ochre`.
      |
      |   * Meep the moop.
      |   * But don't bleep the bloop.
      |
      | Then apply `bar` as a transformation.
      |
      | Parameters:
      |
      |   ~ foo: a [Foo](Fighter::Foo).  Must not be NULL, Null, null, nil,
      |          None, Nothing, or undef.
      |   ~ bar: a [Bar](Dive::Bar).
      |
      | Returns: True on success, false on failure.
      |*/

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

I share your reticence.  In general, reStructuredText is unambiguous but also
unintuitive. :\

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

You think so, eh?

The funny thing is that reStructuredText "grid tables" (which come from Emacs
"table mode") look as though they belong in Markdown -- because they look
great as plain text!

    http://daringfireball.net/projects/markdown/

    The overriding design goal for Markdown’s formatting syntax is to make it
    as readable as possible. The idea is that a Markdown-formatted document
    should be publishable as-is, as plain text, without looking like it’s been
    marked up with tags or formatting instructions. While Markdown’s syntax
    has been influenced by several existing text-to-HTML filters, the single
    biggest source of inspiration for Markdown’s syntax is the format of plain
    text email.

"Grid tables" may be verbose, but their borders look like graphical elements,
not "tags or formatting instructions".

In contrast, the MultiMarkdown table syntax never looks good in plain text,
even with your proposed improvements -- it looks like something out of
reStructuredText, because the syntax is obviously unnatural.

    http://justatheory.com/computers/markup/markdown-table-rfc.html

However, tables aren't a must-have feature for our doc comments.  The two
features missing from Markdown that we need are:

  * Metadata
  * API links

Marvin Humphrey

Mime
View raw message