jashkenas / docco

Literate Programming can be Quick and Dirty.
http://ashkenas.com/docco/
Other
3.55k stars 571 forks source link

Perfect whitespace control by `-l plain-markdown` #403

Open ancms2600 opened 5 years ago

ancms2600 commented 5 years ago

I suggest everyone would benefit from this being the new plain-markdown.jst template going forward:

<%
for (const section of sections) {
    const docsText = section.docsText
        .replace(/^\s*(\/\*\*| \*\/| \* ?)/gm,'')
        .trim();

    if ('' !== docsText) { %><%=
        docsText
%>

<%
    }

    if ('' !== section.codeText.trim()) { %>
`%><%``js
<%=
        section.codeText
            .replace(/\s$/,'')
            .replace(/^(?:\s*[\r\n])+/,'')
            .replace(/(?:[\r\n]\s*)+$/,'')
%>
`%><%``

<%
    }
}
%>

Rationale:

...and my language file, for anyone else who also likes to mix use JSDocs with Docco:

{
  ".js": {"name": "javascript", "symbol": "(//|/\\*\\*|\\*/|\\*)"}
}

For an example, I like to do my JSDocs like this, so they work in Markdown, as well as IDE:

    /**
     * ### _id(t)
     * Required by all MongoDB documents,
     * and is a type of `ObjectId` from its own collection.
     *
     * type + name | description
     * ---|---
     * @param {string} t - | Name of model.
     * @returns {object} - | Instance of validation rule.
     */
    COMMON_SCHEMA._id        = t => field().objectId(t);

Currently invoking like:

# Makefile
documentation:
    yarn global add diagrams docco
    docco -t "docs/_docco_template.jst" -L "docs/_docco_languages.json" -c "/dev/null" -o "docs/" "shared/public/models/schema.js" && \
    mv docs/shared/public/models/schema.html docs/schema.md && \
    rm -rf docs/shared docs/null

Sorry, was too lazy to fork and PR this.