gjtorikian / biscotto

UNMAINTAINED. CoffeeScript API documentation tool that uses TomDoc notation.
https://gjtorikian.github.io/biscotto/
MIT License
105 stars 18 forks source link

Rendered documentation includes options in the description #78

Open balupton opened 9 years ago

balupton commented 9 years ago

If I have:

# Public: The exported CSON singleton
class CSON

    # Public: Converts an {Object} into a {String} of the desired format
    #
    # If the format option is not specified, we default to CSON
    #
    # data - {Object} The data to convert
    # opts - {Object} The options (options may also be forwarded onto the parser library)
    #        :format - {String} The format to use: "cson" (default), "json", "coffeescript", or "javascript"
    #        :cson - {Boolean} Whether or not the CSON format should be allowed (defaults to `true`)
    #        :json - {Boolean} Whether or not the JSON format should be allowed (defaults to `true`)
    #
    # Returns {String} or {Error}
    createString: (data, opts) ->
        return @action('createString', 'create', 'String', data, opts)

It's being rendered like:

screenshot 2015-02-06 01 15 44

Which is not what we expect or want.

Using the command:

/Users/balupton/Projects/cson/node_modules/biscotto/bin/biscotto -n CSON --title "CSON API Documentation" -r README.md -o docs src - LICENSE.md HISTORY.md

Tried with Biscotto versions 2.3.1, 2.3.0, and 2.2.4 (failed on 2.1) - all produce the same result

Source file is: https://github.com/bevry/cson/blob/6991fc9a7577341ea05ca6260a448d4aa3ea7d23/src/lib/cson.coffee

Rendered doc file is: https://github.com/bevry/cson/blob/6991fc9a7577341ea05ca6260a448d4aa3ea7d23/docs/classes/CSON.html

adam-lynch commented 9 years ago

+1

SusanthCom commented 9 years ago

:+1:

Even the case of Examples are same. Placing parameters, returns, examples as a part of description is duplicating and is less readable too. :disappointed:

Documents should be easy to read and no duplicates.