Doesn't work well with React.js projects

[levibuzolic]

Related to #182. Codo doesn't work well with React projects.

Example One

Source Code

'use strict'

React = require('react')

###
This is an example component.

@example Simple usage
  <ExampleComponent className="test" />

@param [String] className Classes to be applied to the component.
###
ExampleComponent = React.createClass
  displayName: 'ExampleComponent'

  render: ->
    React.DOM.div({}, 'example')

module.exports = ExampleComponent

Result

This would be the preferred way to define documentation, however this (as probably expected) results in only the file being listed in the tree with the above documentation generated.

I did however find a slight workaround to get some form of documentation working.

Example Two

Source Code

'use strict'

React = require('react')

ExampleComponent = React.createClass
  displayName: 'ExampleComponent'

  render: ->
    React.DOM.div({}, 'example')

###
This is an example component.

@example Simple usage
  <ExampleComponent className="test" />

@param [String] className Classes to be applied to the component.
###
module.exports = ExampleComponent

Result

Obviously not ideal, but at least there's some output.

Suggestion

In addition to fixing the bug with no output on React.createClass and the issues around CommonJS exports, I think it would be great to be able to manually specify a class in a block of documentation without any relationship to actual code using something like a @class tag in the following form:

###
@class ExampleComponent

This is an example component.

@example Simple usage
  <ExampleComponent className="test" />

@param [String] className Classes to be applied to the component.
###

And then have that class name be picked up, listed in the Classes list.

[inossidabile]

This is not an idiomatic Coffee class. Codo is meant to support Coffee-Script not all the "classish" extensions every new framework adds to javascript. And it will not no matter how popular the framework is.

The main reason for that is that "class" in Coffee-Script is a term. And what you are trying to name "class" is an expression. The term is static. The expression is dynamic. Dynamic expression can not and should not be documented this way. Please take a look at Literate Coffee Script instead.

[mwawrusch]

Quite sad and disappointing, as it makes both codo and coffeedoc.info completely useless for a lot of people.

On Tue, Sep 2, 2014 at 11:13 PM, Boris Staal notifications@github.com wrote:

This is not an idiomatic Coffee class. Codo is meant to support Coffee-Script not all the "classish" extensions every new framework adds to javascript. And it will not no matter how popular the framework is.

The main reason for that is that "class" in Coffee-Script is a term. And what you are trying to name "class" is an expression. The term is static. The expression is dynamic. Dynamic expression can not and should not be documented this way. Please take a look at Literate Coffee Script instead.

— Reply to this email directly or view it on GitHub https://github.com/coffeedoc/codo/issues/183#issuecomment-54256090.

Martin Wawrusch p: +1 310 404 1698

modeista.com - Connect With Style fanignite.com - ALPHA - Create Your Mobile App In 30 Seconds wawrusch.com - Personal Blog codedoctor.co - Professional Blog

Follow me on twitter at @MartinWawrusch http://twitter.com/MartinWawrusch

[levibuzolic]

Thanks for the suggestion of Literate Coffee Script, however I found your reply somewhat dismissive.

I'm working on a large project that is largely codo documented CoffeeScript classes in the proper sense, however some of our files aren't classes (as is the case with any project) and it would be a huge pain to employ two separate documentation systems in order to properly document the project.

Maybe a more appropriate issue for me to have raised would have been the following:

Codo does not support any form of documentation on expressions

Example code

###
Basic documentation of expressions should be rendered by codo
###
module.exports = AnyJSLibrary.extend

  ###
  This method does things.
  ###
  someMethod: ->
    # do things

Some sort of output would be expected, even just the first comment. Instead codo renders a undocumented blank file entry.

[inossidabile]

Like I stated earlier: expression is not a structural entity. someMethod is not really a method. It's a lambda given inside of a hash argument. I can compose the same evaluation in hundreds of different ways. Codo can not support all of them. Making random expressions documentable by making another section "expressions" is simply a bad idea. The generated documentation will be useless.

In theory we could mark an expression as a class with special tag. However the syntax tree will differ depending on how another framework decided to implement its own classes. So it can not be reasonably solved inside of docblock as well.

What can be done – we can allow the dynamic extension of entities defined in lib/entities to allow creation of plug-ins cooked specifically for particular framework. So you describe your own rules of what Codo think "Class" is and how it finds its methods. The current architecture allows doing that easily. To be honest, Codo 2 was designed to allow that in future.

I however can not do that right now. Not even in nearest future. If you want to – PRs are very welcome and I could find time to help. That's all I have to offer.

[levibuzolic]

Thanks Boris,

When I get a chance I'll look into putting up a PR to at least stopping codo from stripping comments completely from the above case. Then will go from there. :+1:

[adtaylor]

I've had some success using the mixin flag and moving the React.createClass to the exports. It's far from perfect but does mean we get some docs.

# Example Component
#
# @mixin
#
ExampleComponent = 

  # --------------------------------------------
  # Defaults
  # --------------------------------------------

  propTypes: {}
  mixins: []

  # --------------------------------------------
  # Getters & Checkers - get/has/can/is
  # --------------------------------------------

  getInitialState: ->
  getDefaultProps: ->

  # --------------------------------------------
  # Lifecycle Methods
  # --------------------------------------------

  componentWillMount: ->          # add event listeners (Flux Store, WebSocket, document)
  componentWillReceiveProps: ->   # change state based on props change
  componentDidMount: ->           # data request (XHR)
  componentWillUnmount: ->        # remove event listeners

  # --------------------------------------------
  # Private methods
  # -------------------------------------------- 

  # Parse server data for hydration
  #
  # @param [Object] data Data from server
  #
  _parseData: (data)->

  # --------------------------------------------
  # Event handlers
  # --------------------------------------------

  # Handle click from Clicker
  #
  # @param [Object] e Synthetic click event
  #
  _handleClick: (e)->

  # --------------------------------------------
  # Render methods
  # --------------------------------------------

  render: ->

module.exports =  React.createClass(ExampleComponent)