Making codo extendable about codo HOT 7 CLOSED

Making codo extensible would be great. To implement a tag extension three steps comes to my mind:

1. Adding a CLI option to require a codo plugin module.
2. Call a defined extension module function when parsing the comment, adding the results to the Doc node.
3. Add customization points to the templates, allow the extension module to hook into these and call it with the Doc node, adding the output to the template.

I don't plan to implement this by myself anytime soon, because I first want to work on some more basic features, like @overload and reference tags. After that I plan to start working on coffeedoc.info to have some kind of rubydoc.info for CoffeeScript.

Optimally implementation starts when someone want to implement an extension, so we work for a real use case and can see what is really needed to support the extension needs. Good examples are specific tags or markers for a framework.

from codo.

Yes, this would be nice. Here are a few things that would be very nice to have:

class @nestedclass

I have classes like this in Tower.js:

class Tower.Model.Relation.HasMany extends Tower.Model.Relation
  class @Scope extends @Scope

But the output is this: Class: this.Scope (doc/classes/this/Scope.html). Maybe that's a bug... It should be able to build the full namespace out of that, Tower.Model.Relation.HasMany.Scope.

Nested mixins/modules

I'm also doing this (abbreviated code):

Tower.Model.Relations =
  ClassMethods:
    hasOne: (name, options = {}) ->
      @relations()[name]  = new Tower.Model.Relation.HasOne(@, name, options)

  relation: (name) ->
    @relations[name] ||= @constructor.relation(name).scoped(@)

The issue is, that ClassMethods is being treated as a constant by codo, when it's just a nested module.

I would like to be able to do this:

# @module
Tower.Model.Relations =
  # @module
  ClassMethods:
    hasOne: (name, options = {}) ->
      @relations()[name]  = new Tower.Model.Relation.HasOne(@, name, options)

  relation: (name) ->
    @relations[name] ||= @constructor.relation(name).scoped(@)

I imagine other people may be building nested modules. However, the way I'm using them here (which is modelled after ActiveSupport::Concern in Rails), is probably application-specific and shouldn't be included in codo core.

What would be awesome is if I could tell codo to treat anything in the ClassMethods nested module to convert those to class variables, and anything in InstanceMethods (or just at the top level Tower.Model.Relations module) treat as an instance method.

Add module methods to classes

Given this:

class Tower.Model

require './model/relations'

Tower.Model.include Tower.Model.Relations

I would like to somehow show all of those Tower.Model.Relations class and instance methods on the Tower.Model documentation page. I saw the @include/@extend discussion, just putting another example use case.

Here are some options:

# Works like ActiveSupport::Concern, looking for `ClassMethods` and `InstanceMethods` on the module.
# This would be ideal.
# 
# @concern Tower.Model.Relation
class Tower.Model

# More explicit...
# 
# @include Tower.Model.Relation.InstanceMethods
# @extend Tower.Model.Relation.ClassMethods
class Tower.Model

Documentation for dynamic methods

I also use this in a few places to decrease the size of the final .js file.

For example, see these two classes:

• https://github.com/viatropos/tower/blob/master/src/tower/model/scopes.coffee#L15
• https://github.com/viatropos/tower/blob/master/src/tower/model/scope.coffee#L72

In the Tower.Model.Scope modules (Queries, Persistence, etc.), I implement a set of methods. Then in those two classes linked above, I iterate through that set of methods and add them to the Tower.Model class. This makes it so I can do this essentially:

class Tower.Model.Scope
  @methodsToCopy: ["where", "create", "update", "destroy"]

  where: ->

  create: ->

  update: ->

  destroy: ->

class Tower.Model

for method in Tower.Model.Scope.methodsToCopy
  do =>
    # need some documentation for these methods
    Tower.Model[method] = ->
      @scope()[method](arguments...)

How can I document those?

You could do it like this (referencing how YARD allows documenting dynamic methods):

##
# @method invisibleMethod

So maybe you could do something like that here:

# @module
Tower.Model.Scopes =
  ClassMethods:
    scope: (name, scope) ->
      @[name] = if scope instanceof Tower.Model.Scope then scope else @where(scope)

  ##
  # @method where
  #   Description, as normal.  Everything is just indented.
  #   
  #   @param [Object] conditions key/value pairs

Just some ideas. Let me know if there is anything I can help with, digging into the source...

Thanks.

from codo.

The issue with the nested class has been fixed and they are now detected properly. Codo operates on the CoffeeScript parser tree and every node constellation must be added to the Codo parser to be recognized. Initially I just implemented the common patterns and we have to add the more advanced styles gradually. So keep on filing issues whenever you see something that's not recognized, I'll happily add it :P

I see no problem with adding @concern directly to Codo. Sure, it's currently application specific, but it's a nice pattern and others may want to implement it also. As long as there isn't a conflict with other tags I'm fine with it, and in this specific case I cannot see the problem, because the intention of objects like ClassMethods and InstanceMethods is crystal clear. What do you think @inossidabile ?

Also the suggested @method implementation is great and I'll like to add them when we have to extend the doc parser to support the @overload tag (see #19), since they also work with tag indention.

Thanks @viatropos for the great suggestions and also the issues you have filed so far, I really appreciate it. Btw. Tower looks great and I plan to build coffeedoc.info with it for hosting Codo documentations.

from codo.

Oh man, having that @concern tag would be awesome. This all sounds very cool, excited to put it to use. Thanks for the great work.

from codo.

Just released Codo 0.6.0 which supports now many new tags:

• tag references: @param (see Class#method)
• method overloads: @overload
• virtual (or dynamic) methods: @method
• mixins @mixin, @include, @extend
• concerns: @concern

Also a TOC will be generated for Markdown files and the frame view is now shown by default (like YARD).

Enjoy!

from codo.

Hell yes, working like a charm.

from codo.

Closing this due my Spring issue cleaning. I'm not going to build something that may be needed sometimes up front. If there's a real use case, open a pull request.

from codo.