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
