usage v. example section consistency/semantics

[abathur]

We typically use three headings for a section that will contain code demonstrating how to use something. In order of frequency, these are "examples", "example", and "usage".

Which should we use? Of these I actually prefer "usage", because it doesn't imply a quantity and therefore never disagrees with the number of things that follow it, though I'm negotiable on this point.

The other hitch is that some of these sections (by any name) are literally just code, while some of them are a mix of code and description. Since the usage section has to support these text-and-code versions as the lowest-common denominator, we have to do one of a couple weird syntax things that are a little clunky when it comes to displaying a code-only section. It may be easier to just show what I mean; here's a prose/code mix:

.. usage::

  Look at this nifty example for how to use environment::

    environment(this_object());

  How cool is that?

Note that the double colon at the end of the first text line is how we start a code/literal section. So when it's code-only:

.. usage::

  ::

    environment(this_object());

So the basic idea is just that code-only usage sections could be much more to-the-point, if we wanted them to be. We could go in a few ways:

• just live with the wasteful/weird syntax for code-only sections
• have separate directives just for creating prose+code and code-only usage sections (though I can't think of any obvious way to name both.)
• just make it a linter violation to have a usage section with no prose (creates the work of going back to add at least minimal descriptions to all violators)
• make the usage-directive code-only, and require any "prose" in usage sections to be in the form of code code comments (creates the work of modifying all of the prose-and-code sections to fit this dictum.

Thoughts?

[abathur]

The option I wanted to work most here was having separate directives, one for quick code-only examples, and one for prose/code mixed sections. I haven't been able to find a pair of words that clearly suggest the difference between these two things.

In thinking about this, I think the high road, in the long run, is probably the third option above: just make it a linter violation to have a usage section with no prose. I haven't really been counting code-only sections, so I'm not sure how prevalent the two types are and how much work it'd take to bring the docs as a whole into compliance with such a linter rule.

Marking as decided but leaving open until implemented.

[abathur]

I have implemented a linter which requires all usage sections have at least one paragraph node. Could do a smarter check later to enforce more rigid standards (i.e., each literal/code block in a usage section should be preceded by a paragraph node, etc.)