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 03:09:10 GMT
On Fri, May 18, 2012 at 11:57 AM, David E. Wheeler
<david@justatheory.com> wrote:
> 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

Heh.  Well, even though the end result is not my favorite doc comment format,
I think the C# people made some really interesting design choices, and that we
can learn from what they did!

Let's consider how various documentation systems, both real and theoretical,
stack up against the C# XML system according to several criteria.

  ~ Learning curve
  ~ Metadata: Can descriptions of method parameters, return values, etc. be
    extracted as structured data?  If so, that gives you a lot of options for
    output, export and manipulation.
  ~ Expressivness: How much can you do within the main description?  Bullet
    lists?  Code blocks?  (Note that *all* these documentation systems allow
    embedded HTML or XML which can be transformed to HTML.)
  ~ API links: Is it possible to link to an external class, a method in an
    external class, a subject heading, etc?
  ~ Conciseness
  ~ Source legibility: It's valuable for the format to be both easy to read
    and easy to write.

C# XML comments:

  ~ Learning curve: Very good if you already know Java and/or XML.  Anyone who
    knows XML already knows the syntax, so you only have to learn the
    semantics.  And since the semantics are basically the same as Javadoc's, if
    you know both XML and Javadoc, you already grok this format!
  ~ Metadata: Yes, via XML tags and properties.
  ~ Expressiveness: Zilch without XML/XSLT.
  ~ API links: Yes.
  ~ Conciseness: Dreadful.
  ~ Source legibility: Horrible -- considerably more laborious to either read
    or write in comparison to plain text or lightweight markup.

reStructuredText inside C multi-line comments:

  ~ Learning curve: Fair to poor.  The format is not well-known.  Given
    examples it's not difficult to cargo cult, but the syntax is not always
    intuitive.
  ~ Metadata: Yes, via field lists (and definition lists?).
  ~ API links: I think so.
  ~ Expressiveness: Outstanding, if you are motivated to learn the syntax.
  ~ Conciseness: Decent.  Not as good as Markdown for code blocks.
  ~ Source legibility: Decent.  It looks like plain text with the occasional
    weird and distracting punctuation construct thrown in.

Plain Markdown inside C multi-line comments:

  ~ Learning curve: Good.  Markdown is simple and fairly popular.
  ~ Metadata: No.  This is a significant drawback.
  ~ API links: No.  A severe drawback. :(
  ~ Expressiveness: Good.  Missing some extended features.
  ~ Conciseness: Outstanding.
  ~ Source legibility: Outstanding.  Tied with Javadoc for the easiest format
    to both read and write.

Markdown with @tags and API links inside C multi-line comments:

  ~ Learning curve: Fair.  Markdown is reasonably well known and easy to
    learn.  @tags are well known primarily via Javadoc, and easy to learn
    via cargo culting.
  ~ Metadata: Yes, via @tags.
  ~ API links: Yes.
  ~ Expressiveness: Same as plain Markdown.
  ~ Conciseness: Outstanding.
  ~ Source legibility: Very good... but non-standard.

POD inside C multi-line comments:

  ~ Learning curve: Good.  Easy things are easy, hard things are possible.
  ~ Metadata: No.
  ~ API links: Yes.
  ~ Expressiveness: Excellent.  POD is full-featured.
  ~ Conciseness: Poor, particularly with lists.
  ~ Source legibility: Good in general, but has major flaws, e.g. nested
    lists.

Javadoc:

  ~ Learning curve: Good.  Well known and simple.
  ~ Metadata: Yes, via @tags.
  ~ API links: Yes.
  ~ Expressiveness: Fair to poor.  Javadoc relies on metadata for common
    constructs -- other than that you're going to need HTML.  It's the
    opposite of formats like POD and Markdown which rely on the user to make
    most decisions about presentation.
  ~ Conciseness: Outstanding.  Using the first sentence as an implicit summary
    is genius, and @tags are extremely compact.
  ~ Source legibility: Outstanding.  As easy to read and write as Markdown.

Scaladoc:

  ~ Learning curve: Good and bad.  Easy to get started if you know Javadoc...
    but then you have to learn the wiki syntax.
  ~ Metadata: Yes, via @tags.
  ~ API links: Yes.
  ~ Expressiveness: Outrageously powerful and complex.  In addition to the
    wiki syntax, also supports variables and documentation inheritance with
    macro substitution!
  ~ Conciseness: Fair to good.  The wiki-like syntax is not always minimalist.
  ~ Source legibility: Decent.  Similar to Javadoc until you use the
wiki syntax.

Marvin Humphrey

Mime
View raw message