From: Jean Privat <jean@pryen.org>
Date: Tue, 16 Dec 2014 04:16:20 +0000 (-0500)
Subject: Merge: Doc down
X-Git-Tag: v0.7~36
X-Git-Url: http://nitlanguage.org

Merge: 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.

Pull-Request: #683
Reviewed-by: Lucas Bajolet <r4pass@hotmail.com>
Reviewed-by: Jean Privat <jean@pryen.org>
---

605d9e3e5503613b96564a94a8173ef5e68e1951