Markdownish "header blocks"

[jkeiser]

Like this:

MyClass:
=======

MyFunction1:
------------
:x*x

MyFunction2:
------------
:x*x

=== is a top level header; --- is a second level header; and === or --- are ended by ===, ---, ___, or EOF.

Indent is significant as well:

MyClass:
=======

    SubClass:
    =========

    MyFunction1:
    ------------
    # This is in SubClass.
    :x*x

    MyFunction2:
    ------------
    :x*x

OuterFunction1:
--------------
# this is in MyClass, not in SubClass.

[jkeiser]

Comments need to work between the header and the name:

MyClass: #

  This class implements the Gettysburg Address.

  If this is called less than four score and seven years after the beginning of the universe,
  this will throw a `MuchTooEarlyException`.

#
=======

Square: #

  This is my function.
  There are others like it,
  but this one is mine.

  It squares things.

#
-------

:x * x

Cube: #

  This is my function.
  There are others like it,
  but this one is mine.

  It cubes things.

#
-------

:x * x * x

Allowing a multiline comment to be ended by ___ / === / --- would allow it to look like this, which is close to ideal:

MyClass: #

  This class implements the Gettysburg Address.

  If this is called less than four score and seven years after the beginning of the universe,
  this will throw a `MuchTooEarlyException`.

=======

Square: #

  This is my function.
  There are others like it,
  but this one is mine.

  It squares things.

-------

:x * x

Cube: #

  This is my function.
  There are others like it,
  but this one is mine.

  It cubes things.

-------

:x * x * x

Making a multiline comment like the above, but allowing the ==== to start with a hash, seems to capture the fact that "the prior stuff was a comment" succinctly, as well:

MyClass: #

  This class implements the Gettysburg Address.

  If this is called less than four score and seven years after the beginning of the universe,
  this will throw a `MuchTooEarlyException`.

#=======

Square: #

  This is my function.
  There are others like it,
  but this one is mine.

  It squares things.

#-------

:x * x

Cube: #

  This is my function.
  There are others like it,
  but this one is mine.
  It cubes things.

#-------

:x * x * x

[jkeiser]

Because of ___ ending a block, optional separators can be used to enhance clarity, as well:

MyClass: #

  This class implements the Gettysburg Address.

  If this is called less than four score and seven years after the beginning of the universe,
  this will throw a `MuchTooEarlyException`.

=======

Square: #

  This is my function.
  There are others like it,
  but this one is mine.

  It squares things.

-------

:x * x

________

Cube: #

  This is my function.
  There are others like it,
  but this one is mine.

  It cubes things.

-------

:x * x * x

_______

[jkeiser]

The comment suggestions above make it too hard to scan for the name of the current thing (you scan for the ====, but that's at the end of the comment block). One way we could do comments that even further reduces eye weirdness: anything that's indented after the declaration becomes a comment. Sort of looks like a "sidebar" or quoted comment inn markdown.

MyClass
=======

  This class implements the Gettysburg Address.

  If this is called less than four score and seven years after the beginning of the universe,
  this will throw a `MuchTooEarlyException`.

Square
------

  This is my function.
  There are others like it,
  but this one is mine.

  It squares things.

:x * x

Cube
----

  This is my function.
  There are others like it,
  but this one is mine.

  It cubes things.

:x * x * x

[jkeiser]

The markdown syntax has always made me a little uncomfortable because I have to update the number of "=" and "-" when I change the length of the title, making copy/paste difficult. It also takes up more vertical space than I'd like. An alternative that solves both of these concerns:

=== MyClass ===

  This class implements the Gettysburg Address.

  If this is called less than four score and seven years after the beginning of the universe,
  this will throw a `MuchTooEarlyException`.

--- Square ---
  This is my function.
  There are others like it,
  but this one is mine.

  It squares things.

:x * x

--- Cube ---
  This is my function.
  There are others like it,
  but this one is mine.

  It cubes things.

:x * x * x