coffeedoc / codo

CoffeeScript API documentation generator. It's like YARD but for CoffeeScript!
Other
624 stars 92 forks source link

Support multiline @param and @option #257

Open DiThi opened 6 years ago

DiThi commented 6 years ago

An example from my code:

    # Loads objects that are visible from any point of view, returns a promise
    # @option options fetch_textures [boolean] Whether to fetch textures when they're not loaded already.
    # @option options texture_size_ratio [number] Quality of textures specified in ratio of number of pixels.
    # @option options max_mesh_lod [number] Quality of meshes specified in LoD polycount ratio.
    # @return [Promise]
    load_visible_objects: (options) ->
        visible_objects = for ob in @children when ob.visible then ob
        return fetch_objects(visible_objects, options).then(=>this)

Option lines are way too long, trip the linter and more importantly, they're difficult to read since the rest of the code now fit in 80 columns. I picked a random example with relatively short descriptions, there are instances where I need to explain much more. In those cases I explain in the function body and then in the parameter/option I say "see above" or something, which is ugly.

Examples of what I'd like codo to support:

    # @option options texture_size_ratio [number]
    #         Quality of textures specified in ratio of number of pixels.
    # @option options texture_size_ratio [number] Quality of textures specified 
    #                                             in ratio of number of pixels.