On Fri, May 18, 2012 at 11:57 AM, David E. Wheeler <[email protected]> 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
