How to Handle Docstrings

[cooncesean]

We're having an internal discussion on our team about the best practice for handling docstrings. In Python, we'd do something like:

"""This is a module level docstring."""

class SomeClass(object):
    """This is a class level docstring."""

   def some_method(self, arg1, arg2):
       """This is a method level docstring."""

In coffeescript, we'd like to mimic the pattern:

### This is a module level docstring. ###

SomeObject =
    ### This is an object level docstring. ###

    someMethod: ->
      ### This is a method level docstring. ###
      ...
      # Some inline comment
      ...

I like this approach as it distinctly separates "docstrings" from inline comments, but it appears that triple ### renders a multi-line comment to the compiled javascript -- which is probably undesired in most cases.

Any guidance would be helpful - thx :)

[guaka]

+1
I just wanted to leave a similar issue now. Happy to find this one, which is already much more elaborate than what I had in mind: what's the best way to document functions (and classes) in CoffeeScript?
Mimicking Python makes a lot of sense.

[anonomis]

Why is it undesired?

[cooncesean]

@anonomis Our concern was that it adds unnecessary weight code to production code.

[anonomis]

@cooncesean If you mangle your code through a minimizer before reaching production (which I strongly encourage you to do) the comments will be omitted anyway.

[cooncesean]

@anonomis Thank you, that's a very good idea. So, in your opinion, triple pound (###) seems like a reasonable way to go?

[mjrusso]

We've had success with using JSDoc directly. For example:

    ###*
     * The version number of this library.
     *
     * @member
     * @instance
     * @readonly
     * @memberof Library
     * @type {string}
    ###
    version: (require "../../package.json").version

For other options, also see:

• Docstrings jashkenas/coffeescript#193
• https://github.com/omarkhan/coffeedoc