privat/nit — pull request #683 by Morriar (2014-08-25 02:47:00+00:00)
Title: Doc down

Please disregard commits before 0a57951, they belong to #680.

This pull request remove the module `src/markdown` and use the newly introduced `markdown` parser instead.

## Major changes considering Nit comments

### Synopsys line

Synopsys line must be followed by a blank line for multilines comments according to the Markdown paragraph syntax.

Example before:

# foo doc
fun foo do end

# bar doc
# more doc or doc unit
fun bar do end

After:

# foo doc
fun foo do end

# bar doc
#
# more doc or doc unit
fun bar do end

This is boring, I know, but it allows Nit comment to be properly parsed by most of the markdown parsers.
Also, most of multilne comments are already corrects.

### Code blocks

Code blocks (and doc unit) are now parsed following the correct rule: every line starting with at least 4 spaces is a code block (if not in a nested list).

Example before:

# assert true # was not recognized by nitdoc and nitunit
fun foo do end

After:

# assert true # works in nitunit and nitdoc
fun foo do end

Commit 0b275eb performs those changes on lib/standard as example.

## What's new?

### Full markdown syntax available

All the original markdown syntax is now recognized by the parser (link definitions, blockquotes, nested elements, escape...).
I'm working to add a Github flavoured mode and maby a custom mode for Nitdoc.

### Nitdoc annotations

Some annotations are now recognized in the comments. They do nothing but allow nitdoc to add some style.

Annotation list:

* DEPRECATED
* SEE
* REQUIRE, ENSURE
* FIXME, TODO, NOTE

Syntax:

# Some doc
#
# DEPRECATED: use `bar` instead.
fun foo do end

## TODO

Some tests maybe broken in lib/ and src/ because of the synopsys change, I will update this PR with fixes.

We now have everything we need to work on a Nit flavoured markdown allowing to control nitdoc generation. This is the next step.