coffeedoc / codo Goto Github PK

I've tried to use codo under windows 7 (64bit) but the copying of the assets won't work. It just creates empty css and js files.

I've been able to fix it by replacing

to.once 'open', (fd) -> require('util').pump from, to

with

from.pipe(to)

in the method copy in generator.coffee

I use (and love) a tool called Streamline to manage async code in Node. It's terrific: it lets you write synchronous-looking code that gets transformed (compiled) to regular async code. No new keywords or symbols; it remains syntactically valid JS.

Streamline also supports CoffeeScript, by simply using the compiled JS, and its convention is to prefix the extension with an underscore, so ._js and ._coffee. Thus, could Codo detect ._coffee files too?

Here's an example project of mine I'd love to use Codo (and CoffeeDoc.info) with, but none of the ._coffee files are getting recognized, even if I explicitly specify them on the command-line:

https://github.com/thingdom/node-neo4j

FWIW, GitHub added support for highlighting and detecting these files (as you can see in the repo above) at our request:

github-linguist/linguist#151

Thanks for the consideration!

# Should be overloaded to change fetch limit.
#
#   @return Number of items per fetch
#
fetchLimit: () -> 5

fails
However

fetchLimit: ( ) -> 5

works -- space added between brackets

I tried to build documentation on windows, node 0.6.19, and I get the error

"Cannot generate documentation: Object has no method 'frames'

This error even happens when I try to build the codo documentation, or try to build docs for a blank file or a file with no comments, so I cant see what I could have done wrong.

I've had a little look though the source, and I presume this error is happening somewhere where it tries to access

parent.frames

and similar in theme\default\src\coffee\codo.coffee, but I cant be sure that's the issue.
Sorry if this is some mistake on my part.

Describe that your method can be used in various contexts with various parameters or return types. The first line should declare the new method signature, and the following indented tag data will be a new documentation string with its own tags adding metadata for such an overload.

class Store
  # @overload set(key, value)
  #   Sets a value on key
  #   @param [Symbol] key describe key param
  #   @param [Object] value describe value param
  # @overload set(value)
  #   Sets a value on the default key `:foo`
  #   @param [Object] value describe value param
  set: (args...) ->

The @see tag can be used to reference to URL or other objects.

@see http://example.com Description of URL
@see SomeOtherClass#method
@see AnotherClass.method

See also #20 for a reuse of the resolver.

A class view method description should have links to show/hide the CoffeeScript and JavaScript source code.

Hello! Thank you for this great documentation solution!

I'm running into one problem that I can't seem to resolve...

  # Used to create a new kb.FormattedObservable.
  #
  # @param [String|ko.observable] format the format string. Format: "{0} and {1}" where {0} and {1} would be synchronized with the arguments (eg. "Bob and Carol" where {0} is Bob and {1} is Carol)

and the output is:

[WARN] Cannot find referenced class 0 in class kb.FormattedObservable
[WARN] Cannot find referenced class 1 in class kb.FormattedObservable
[WARN] Cannot find referenced class 0 in class kb.FormattedObservable
[WARN] Cannot find referenced class 1 in class kb.FormattedObservable
[WARN] Cannot find referenced class 0 in class kb.FormattedObservable
[WARN] Cannot find referenced class 1 in class kb.FormattedObservable

How can I escape curly braces in my descriptions? (I also have the same problem is I want to add an object like {name: 'value') into a description.

Cheers,

Kevin

Should we use left bar with tree of classes/methods/files instead of drop downs? This is the default theme for http://api.rubyonrails.org and http://rdoc.info. Besides the fact it's more comfortable to work with drop downs have shown themselves to not work very well on a slow channel.

We will implement this kind of theme for our projects anyway. If you think it would be right I can pull request that as we are ready saving neutral blue colors and styles.

Coffee allows the empty classes declaration. This can often be met in some kind of meta-magic. Empty-name classes should be ignored by codo.

comments like the following don't seem to work:
x = 1 # @todo maybe make this a 3

codo doesn't seem to recognize inline comments at all - it seems like they all have to be on their own line.

Add a new command codo server that starts a local server from the document directory. This is necessary to avoid the restrictions with the file:// protocol.

Example:

Comments for this function don't appear in documentation.

# Initialize a new router.
#
# @param options [Object] initialization options
#
initialize: (options)->

It works if you change (options)-> to (options) ->. The parser should accept both cases since whitespace is optional in CoffeeScript syntax. I think the regex at parser.coffee#L133 is at fault.

| # Function
  [$A-Za-z_\x7f-\uffff][$\w\x7f-\uffff]*\s*:\s+(\(.+\)\s+)?[-=]>
| # Function
  @[A-Za-z_\x7f-\uffff][$\w\x7f-\uffff]*\s*=\s+(\(.+\)\s+)?[-=]>

My regex fu isn't quite good enough to figure this one out right now.

Github pages are likely the place where a lot of project will store their API docs. However by default Github will ignore the filenames that start from underscore. To fix this behavior you can put ".nojekyll" file to your root. It's not very clear for most of people though.

To respect them I think we should rename the file where Codo keeps elements index (it's _index.html) now. Or maybe we can put .nojekyll to the root since it's quite a fantastic case to use the same root for jekyll.

I'm not really sure if we should care about it at all nor I'm sure which is more correct way to solve this that's why I didn't do a pull request. But I trust that if we can let people avoid some confusing situations we should do it.

It seems that when you leave off --private private methods are still listed. Although it does seem to filter out classes marked as private.

I would expect the private flag to affect visibility of both private classes and private methods of public classes.

The @example tag doesn't allow for no title, so this ends up printing out @example buildAlert('!') as a string rather than title + code:

class Generator

  # This @example tag has no trailing whitespace
  #
  # @example
  #   buildAlert('!')
  buildAlert: (x) ->
    alert(x)

But these two print correctly:

class Generator

  # This @example tag does have trailing whitespace
  #
  # @example  
  #   a('!')
  a: (x) ->
    alert(x)

  # This @example has a title
  #
  # @example  A Title  
  #   a('!')
  a: (x) ->
    alert(x)

In @overload sections like this:

# Construct a new Observer
#
# @overload constructor()
#   Construct new Observer with default options
#
# @overload constructor(options)
#   Constrict new Observer with settings
#   @param [Object] options
#   @option options [String] verbose verbose level
#
constructor: (options={}) ->

@option parts don`t render in output html docs at all.

I use @overload at wrong way or it issue?

Hope you don't mind so many feature requests. =)

I've noticed that basic Markdown, e.g. code and italics, in @note and @todo comments doesn't get rendered. Is this by design? If not, it would be great to have this support.

Thanks for the consideration!

Properties should be presented like the methods, so all tags can be presented also for a property.

If a Class/Module has children, the link doesn't seem to be working in the upper-right-corner dropdown menus for Classes/Modules.

- Tower
  - Model # this is a valid class, but doesn't click
    - Attribute # this is a valid class, but since it has no children, it clicks

First of all well done, codo is absolutelly brilliant in what it does, at least when it comes to its main focus, "focused on CoffeeScript class syntax for classical inheritance".

Nevertheless, Coffescript is an excellent functional language as well (or mostly!) and it will be a shame if this issue is intentional and not a bug :

I have a file.coffee which has a sole function (an overloaded underscore proxy). Although its well documented according to codo specs (in regards to @params, @return, @options etc) the function is completely omitted from the generated docs.

When I just add class Foo on top of it and convert it to a class method, boom it appears.

My problem is that this function doesn't belong to any class (and I've been a Java programmer for a decade!) .
There is simply no other class to inherit from/inherited by, in behaviour or state. There are no instances of it that need to have a state (for now!). Its like _.each with oveloaded options. Its just a function.

But I love codo :-) so should it be documented and appear under files or somewhere else, or is it intentionally left out ?

Export all classes/mixins and methods to a JSON file that will be included in the main document. Implement a command-T like window to find entries quickly and navigate to it.

The file view should display a TOC generated from the headers of the markdown file.

It would be nice to make codo easier to extend. This point came up briefly in #31.

Things that come to my mind would be to make the parser extendable to allow for parsing additional of additional (non-standard?) tags or support a different syntax (jsoc?). This was also pointed out by @inossidabile in #31 as well as the YARD having similar functionality.

I wouldn't know directly how to implement this but maybe we can come up with a strategy and some features/requirements in this issue and implement from that.

I'm trying to add in directories of "extra" markdown files, but the static asset links aren't correctly being generated (say for directory "foo/bar/my_file.md"). I think the following diff will fix this:

$ git diff src/generator.coffee 
diff --git a/src/generator.coffee b/src/generator.coffee
index cf2adda..de59d73 100644
--- a/src/generator.coffee
+++ b/src/generator.coffee
@@ -126,10 +126,16 @@ module.exports = class Generator
       try
         content = fs.readFileSync extra, 'utf-8'
         content = marked content if /\.(markdown|md)$/.test extra
+        numSlashes = extra.split('/').length - 1
+        assetPath = ''
+        assetPath += '../' for slash in [0...numSlashes]
         filename = "#{ extra }.html"
+
         @templater.render 'file', {
-          path: ''
+          path: assetPath
           filename: extra,
           content: content
           breadcrumbs: [

I'm not doing a pull request, as I don't fully understand the generation path, and I'm very behind the curve on using Guard for auto-gen, and what I have done so far gens a lot of extra JS code.

So, hopefully this points in the right direction. If there is a different way to get nested directories of markdown files correctly included, please let me know.

Codo should support tag references to meta data from other methods can be reused:

class User
  # @param [String] username the nam of the user to add
  # @param [Number] uid the user ID
  # @param [Number] gid the group ID
 constructor: (username, uid, gid) ->

class UserHelper
  # @param (see User#constructor)
  addUser: (username, uid, gid) ->
    new User(username, uid, gid)

  # @param username (see User#constructor)
 addRootUser: (username) ->
    new User(username, 0, 0)

Hey there,

Great work on this library and tool. I'd love to use it for my projects, but a few of them are still on Node 0.6 for the time being since they're big and upgrading will require a bit of time.

It seems that Codo should work fine on Node 0.6 (the package.json says >= 0.4), but right off the bat in codo.coffee, the fs.existsSync call fails. (It should probably be fs.existsSync || path.existsSync for backwards-compatibility.)

But even after changing that, it fails with a cryptic error that I haven't been able to debug:

Cannot generate documentation: undefined is not a function
TypeError: undefined is not a function
    at /usr/local/lib/node_modules/codo/node_modules/async/lib/async.js:229:13
    at /usr/local/lib/node_modules/codo/node_modules/async/lib/async.js:86:13
    at Array.forEach (native)
    at /usr/local/lib/node_modules/codo/node_modules/async/lib/async.js:26:24
    at /usr/local/lib/node_modules/codo/node_modules/async/lib/async.js:85:9
    at /usr/local/lib/node_modules/codo/node_modules/async/lib/async.js:228:9
    at Object.<anonymous> (/usr/local/lib/node_modules/codo/node_modules/async/lib/async.js:168:23)
    at Object.inputs (/usr/local/lib/node_modules/codo/src/codo.coffee:194:20)
    at /usr/local/lib/node_modules/codo/node_modules/async/lib/async.js:467:24
    at /usr/local/lib/node_modules/codo/node_modules/async/lib/async.js:86:13

I'm on Node 0.6.16 and Codo 1.3.0 FWIW.

If this is too much trouble, I understand. But if not, it'd be great to be able to use this. =) Thanks for the consideration! And great work again.

Cheers,
Aseem

I've noticed one bug and one maybe-a-bug about Codo's Markdown rendering.

Using this documentation as a reference:

https://dl.dropbox.com/u/25149872/node-neo4j/doc/index.html

From this source:

https://github.com/thingdom/node-neo4j/tree/feature/documentation

1. The main readme rendering has occasional spaces (whitespace) missing.

   E.g. cmd+F for "aseemk's" — it should be "aseemk's node-neo4j-template app", but instead it's "aseemk'snode-neo4j-template app" (note missing space).

   Same with e.g. "issue tracker" — missing a space before.

   In both cases, I think the cause is when a newline precedes a link or code tag. Source:

   https://raw.github.com/thingdom/node-neo4j/feature/documentation/README.md

2. Readme files like this, and IMHO general class/method/property/etc. documentation, shouldn't break on newlines.

   I understand that this is one of the features of GitHub-flavored Markdown, but even GitHub doesn't use this variant for Markdown documents (like the readme) or on the wiki. (As its page says, it's only used for messages, issues and comments.)

   Thus, at the very least, I think it'd be nice to thus follow GitHub's rendering for the readme. But I think it's even important to not break on newlines for code documentation, since most people wrap source code manually (e.g. at 80 characters). And preserving these newlines in the generated HTML doesn't look great.

   Thanks for the consideration on this one!

Is there support for headings that are greater than level 2, as described in http://daringfireball.net/projects/markdown/basics ?

I attempted to do something like:
# hello
# ### this should be a heading
# more stuff

And the output was just:
more stuff

Thanks in advanced.

I would like to link to methods using abbreviated links but it doesn't look like it's working.

This works:

class User
  a: ->

  # This method calls {User#a}
  b: ->
    a()

  # This method calls {#a}
  c: ->
    b()

But these don't work:

class User
  a: ->

  # This method calls {User#a a()}
  b: ->
    a()

  # This method calls {#a a()}
  c: ->
    b()

Codo should parse link to URL and object references in the class and method description. The resolver is the same as in #18.

In case of using CoffeeScript block comments (I like it for simply folding in Sublime Text and others good pars) in codo v1.1.1 it parsed incorrectly if have indention.

###
Non-indented string, worked
@version v1.1.1
###
class Example

  ###
  Indened by 2 spaces string
  @note Indented block comment not worked
  @return [Integer] just for test
  ###
  constructor : ->

If second comment un-indent like this

  ###
Indented by 2 spaces string
@note Indented block comment not worked
@return [Integer] just for test
  ###
  constructor : ->  

codo parsed block accurately, but its looks strange in code.

Methods have a super swank "[private]" tag on them. But private classes do not. Classes rendered out with the --private flag should have a similar "[private]" tag on them near the top along with all the notes/abstract/TODO messages.

When trying to document a file 'Handler.coffee' inside of a folder named 'coffeescripts', Codo returns

Cannot Parse file coffeescripts/Handler.coffee: ENOENT, no such file or directory 'escripts/Handler.coffee'

Current implementation of referencer allows the . and # delimiters according to the class and instance methods. On the other side everything we receive from mixin is marked as a mixin method.

Inside referencer we do search through mixins. However delimeter-type filters will always reject the mixins methods. So there's totally no way to reference to mixin method. And that's just wrong.

Hey there,

Is there any way to document properties in addition to methods?

There are "simple" properties that you might assign in the constructor:

class Foo
  constructor: (bar, @baz) ->
    @_bar = bar

But there are also getter/setter properties which you might achieve via ES5 or the older (but supported by Node) __defineGetter__/__defineSetter__ methods:

class Foo

  Object.defineProperty @::, 'bar',
    get: -> @_bar
    set: (bar) -> @_bar = bar

  @::__defineGetter__ 'baz', -> @_baz
  @::__defineSetter__ 'baz', (baz) -> @_baz = baz

FWIW, we use these second types of properties extensively in our Node modules since getters/setters makes code so much more readable. Here's a little example that demonstrates:

https://gist.github.com/2506270

Particularly for getter/setter properties -- since they replace the need for getFoo()/setFoo() methods -- it's important to document these guys.

Is there any way to do so currently? If not, might I suggest having a virtual @property tag like the virtual @method tag? E.g.:

# @property bar {String} The lorem of ipsum.
# @note This is undefined when dolor sit amet.
# @private
get bar: -> @_bar
set bar: (bar) -> @_bar = bar

Thanks for the consideration. =)

Aseem

I'm having trouble installing codo. This is my train of thought:

clambert@clambert-linux:/code/pgdev/pg/code33/plugins$ codo
bash: /usr/local/bin/codo: No such file or directory
clambert@clambert-linux:/code/pgdev/pg/code33/plugins$ sudo npm -g ls
/usr/local/lib
(empty)
clambert@clambert-linux:/code/pgdev/pg/code33/plugins$ sudo npm -g install codo
npm http GET https://registry.npmjs.org/codo
npm http 304 https://registry.npmjs.org/codo
npm http GET https://registry.npmjs.org/coffee-script
npm http GET https://registry.npmjs.org/walkdir
npm http GET https://registry.npmjs.org/optimist
npm http GET https://registry.npmjs.org/underscore
npm http GET https://registry.npmjs.org/marked
npm http GET https://registry.npmjs.org/underscore.string
npm http GET https://registry.npmjs.org/mkdirp
npm http GET https://registry.npmjs.org/connect
npm http GET https://registry.npmjs.org/haml-coffee
npm http GET https://registry.npmjs.org/async
npm http 304 https://registry.npmjs.org/underscore
npm http 304 https://registry.npmjs.org/optimist
npm http 304 https://registry.npmjs.org/coffee-script
npm http 304 https://registry.npmjs.org/walkdir
npm http 304 https://registry.npmjs.org/marked
npm http 304 https://registry.npmjs.org/underscore.string
npm http 304 https://registry.npmjs.org/mkdirp
npm http 304 https://registry.npmjs.org/connect
npm http 304 https://registry.npmjs.org/haml-coffee
npm http 304 https://registry.npmjs.org/async
npm http GET https://registry.npmjs.org/wordwrap
npm http GET https://registry.npmjs.org/qs/0.4.2
npm http GET https://registry.npmjs.org/formidable/1.0.11
npm http GET https://registry.npmjs.org/crc/0.2.0
npm http GET https://registry.npmjs.org/cookie/0.0.4
npm http GET https://registry.npmjs.org/bytes/0.1.0
npm http GET https://registry.npmjs.org/send/0.0.3
npm http GET https://registry.npmjs.org/fresh/0.1.0
npm http GET https://registry.npmjs.org/pause/0.0.1
npm http GET https://registry.npmjs.org/debug
npm http GET https://registry.npmjs.org/findit
npm http 304 https://registry.npmjs.org/wordwrap
npm http 304 https://registry.npmjs.org/bytes/0.1.0
npm http 304 https://registry.npmjs.org/cookie/0.0.4
npm http 304 https://registry.npmjs.org/formidable/1.0.11
npm http 304 https://registry.npmjs.org/crc/0.2.0
npm http 304 https://registry.npmjs.org/qs/0.4.2
npm http 304 https://registry.npmjs.org/send/0.0.3
npm http 304 https://registry.npmjs.org/fresh/0.1.0
npm http 304 https://registry.npmjs.org/pause/0.0.1
npm http 304 https://registry.npmjs.org/debug
npm http 304 https://registry.npmjs.org/findit
npm http GET https://registry.npmjs.org/mime/1.2.6
npm http GET https://registry.npmjs.org/range-parser/0.0.4
npm http GET https://registry.npmjs.org/seq
npm http 304 https://registry.npmjs.org/mime/1.2.6
npm http 304 https://registry.npmjs.org/range-parser/0.0.4
npm http 304 https://registry.npmjs.org/seq
npm http GET https://registry.npmjs.org/chainsaw
npm http GET https://registry.npmjs.org/hashish
npm http 304 https://registry.npmjs.org/chainsaw
npm http 304 https://registry.npmjs.org/hashish
npm http GET https://registry.npmjs.org/traverse
npm http GET https://registry.npmjs.org/traverse
npm http 304 https://registry.npmjs.org/traverse
npm http 304 https://registry.npmjs.org/traverse
/usr/local/bin/codo -> /usr/local/lib/node_modules/codo/bin/codo
[email protected] /usr/local/lib/node_modules/codo
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected] ([email protected])
├── [email protected] ([email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected])
└── [email protected]
clambert@clambert-linux:/code/pgdev/pg/code33/plugins$ sudo npm -g ls
npm WARN [email protected] package.json: bugs['name'] should probably be bugs['url']
/usr/local/lib
└─┬ [email protected]
├── [email protected]
├── [email protected]
├─┬ [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ ├── [email protected]
│ └─┬ [email protected]
│ ├── [email protected]
│ └── [email protected]
├─┬ [email protected]
│ └─┬ [email protected]
│ └─┬ [email protected]
│ ├─┬ [email protected]
│ │ └── [email protected]
│ └─┬ [email protected]
│ └── [email protected]
├── [email protected]
├── [email protected]
├─┬ [email protected]
│ └── [email protected]
├── [email protected]
├── [email protected]
└── [email protected]
clambert@clambert-linux:/code/pgdev/pg/code33/plugins$ codo
Error: Cannot find module 'haml-coffee'
at Function._resolveFilename (module.js:332:11)
at Function._load (module.js:279:25)
at Module.require (module.js:354:17)
at require (module.js:370:17)
at Object. (/usr/local/lib/node_modules/codo/src/util/templater.coffee:14:11)
at Object. (/usr/local/lib/node_modules/codo/src/util/templater.coffee:76:4)
at Module._compile (module.js:441:26)
at Object..coffee (/usr/local/lib/node_modules/codo/node_modules/coffee-script/lib/coffee-script/coffee-script.js:22:21)
at Module.load (module.js:348:32)
at Function._load (module.js:308:12)
clambert@clambert-linux:/code/pgdev/pg/code33/plugins$

Thoughts on what I'm doing wrong?

class Foo
  # This is not exposed to the outside world.
  internalToClassClosure = -> alert 'internal!'

  # A normal instance method.
  bar: -> internalToClassClosure

codo will document internalToClassClosure as a method, even though it really isn't. And it's extra weird, because the comments attached to it appear not to be parsed and it's documented as a naked method with no description or markup. It's also reported as an instance method, which isn't technically right at all.

Is the intent to document functions like this? Personally, It's even more private than @private since other internal classes do not have access to it. So I would say it doesn't belong in the docs even with --private. If, however, you disagree then there is definitely a bug with the doc being parsed for functions declared like this.

I've come across a rather odd parsing bug. The issue seems to be quite specific to one particular pattern of code. I've distilled the problematic code down to the following:

class MyClass
    method: (param) ->
        if param?
            doSomething()
        # A comment
        else @_privateMethod param

Which produces the following error message when parsed in Codo:

Cannot parse file bug.coffee: Parse error on line 5: Unexpected 'INDENT'

Changing the if/else block to any of the following seems to resolve the error:

# Don't underscore the method
if param?
    doSomething()
# A comment
else @privateMethod param

# Newline + indent
if param?
    doSomething()
# Comment
else 
    @_privateMethod param

# Remove the comment
if param?
    doSomething()
else @_privateMethod param

# Call a non-class underscored method
if param?
    doSomething()
# Comment
else _privateMethod param

# Indent the comment
if param?
    doSomething()
    # Comment
else @_privateMethod param

I have codo 1.2.3 installed, and here are some various bits of debug output:

Node/NPM versions:

djessup$ npm version
{ http_parser: '1.0',
  node: '0.8.7',
  v8: '3.11.10.17',
  ares: '1.7.5-DEV',
  uv: '0.8',
  zlib: '1.2.3',
  openssl: '1.0.0f',
  npm: '1.1.59' }

Codo verbose output

djessup$ codo -v
Cannot parse file bug.coffee: Parse error on line 5: Unexpected 'INDENT'
Get method value error: { variable: 
   { base: { value: 'options', ancestor: [Circular] },
     properties: [],
     ancestor: [Circular] },
  value: 
   { base: 
      { generated: true,
        properties: [Object],
        objects: [Object],
        ancestor: [Circular],
        tab: '' },
     properties: [],
     ancestor: [Circular] },
  context: 'object',
  param: undefined,
  subpattern: undefined,
  ancestor: 
   { generated: true,
     properties: 
      [ [Circular],
        [Object],
        [Object],
        [Object],
        [Object],
        [Object],
        [Object] ],
     objects: 
      [ [Circular],
        [Object],
        [Object],
        [Object],
        [Object],
        [Object],
        [Object] ],
     ancestor: { base: [Circular], properties: [], ancestor: [Object] } } } [TypeError: Cannot call method 'freeVariable' of undefined]

I'm quite unhappy with current implementation of frames/no-frames view. I agree it could be useful for someone to have non-frame view but I can't agree it's enabled by default and there's no way to change this behavior nor to exclude non-frame view completely.

I was going to split it into two separate templates if it's ok. Is it?

Codo has been developed on WebKit browsers. Test on other rendering engines as well.

Classes should have ability to define @include or @extend references to defined modules. Included/extended methods should appear in classes in the same way inherited methods do.

Right now there doesn't seem to be any link to return to the "home" (readme) view of the generated documentation. It'd be great if there were a persistent one on every page.

E.g. https://dl.dropbox.com/u/25149872/node-neo4j/doc/index.html — the moment you click any class link, there doesn't seem to be any way to return to the root without using the back button. Not ideal after you've clicked a number of times.

(There's an "index" link at the top, but this goes to a class index list. Given that there's already a class list in the left bar, perhaps this could be replaced with a "Home" [or the title of the project] link?)

The class list should be a tree similar to YARD. The tree must automatically expand a tree node when a search result is hidden as child. Also a collapse/expand all feature would be nice.

See #64 and https://github.com/thingdom/node-neo4j/blob/feature/documentation/lib/GraphDatabase._coffee#L370 for more info.

I've gone through one of our public projects and added Codo-style documentation to each file:

https://github.com/thingdom/node-neo4j/tree/feature/documentation

Unfortunately, the generated documentation is close but not quite there:

https://dl.dropbox.com/u/25149872/node-neo4j/doc/index.html

I hope you don't mind if I share the various bugs here in one issue instead of opening up a bunch of separate issues. =)

Take a look at the GraphDatabase class for instance; source:

https://github.com/thingdom/node-neo4j/blob/feature/documentation/lib/GraphDatabase._coffee

It appears that the ### Database: ### comment on line 39 messes up all the documentation for the first few methods. (And it also gets treated as the description for the first method.)

Somehow, the ### Nodes: ### comment on line 118 doesn't cause this problem, and things return to normal for those node methods. But the problem reappears for the ### Relationships: ### comment on line 249.

Things again return to being documented with the query() method, but the overloads' documentation somehow gets nested instead of shown one after the other. And then the next method's documentation also gets nested within the overloads.

Finally, for the PropertyContainer and Relationship classes, none of the methods have any generated documentation; source:

https://github.com/thingdom/node-neo4j/blob/feature/documentation/lib/PropertyContainer._coffee
https://github.com/thingdom/node-neo4j/blob/feature/documentation/lib/Relationship._coffee

You can see that I'm using the strawman @property tag I proposed in #61. The GraphDatabase and Node classes don't use this and so don't have this problem. Here, they seem to be breaking everything.

So this is where I'm at. Quite close! I'd love to know if I'm doing anything wrong, but FYI on these seeming bugs otherwise. Excited to get this working. Thanks again. =)

P.S. Btw, I first tried coffeedoc.info to share the documentation, but it doesn't quite work nearly at all:

http://coffeedoc.info/github/thingdom/node-neo4j/feature/documentation/

Not only do none of the classes have almost any generated documentation, the Path class is missed altogether. It's alos using the latest Codo 1.3.1 (though on Node 0.8), so I'm not sure what's up.

It's quite a common practice for JS to implement modules and mixins using object merges. Due to ruby syntax YARD has no need for some kind of special declarations for modules. But Codo should have one since Object-modules are very important part of structured libraries.

@netzpirat do you have any thoughts on possible implementation of this thing? It looks like we should have ability to mark assignation with something like @module and consider inline Object declaration as a module itself. We should either add @includes and @extends tags to declare which mixins are in use for this class.

Take a look at this for example of modules we have in real life: https://github.com/roundlake/joosy/tree/master/app/assets/javascripts/joosy/core/modules.

Besides that I've seen modules in a lot of wide-known projects like Spine.js. I think maybe @maccman has something to say here.

See #64 and and https://github.com/thingdom/node-neo4j/blob/feature/documentation/lib/GraphDatabase._coffee#L487

For some reason in Firefox, the search frame iframe has display:inline rather than display:none, which results in a large white rectangle obscuring the right half of the documentation page (index.html, class_index.html, etc). The same page looks fine in Chrome.

I want to run codo for some files, but it does not work.

$ codo app.coffee
Cannot parse file app.coffee: ENOENT, no such file or directory ''

I found walkdir only works for a directory

# for direcotry
coffee> walkdir.sync 'routes'
[ '/Users/sixmen/test/routes/index.coffee',
  '/Users/sixmen/test/routes/util.coffee' ]

# for file
coffee> walkdir.sync 'app.coffee'
[ 'app.coffee' ]