jashkenas/docco — pull request #70 by johnnywengluu (2011-11-20 05:16:48+00:00)
Title: Add @ignore comment tag to omit sections from output

Often I want to hide some code from the final output.

One scenario is when I am generating documentation from test files (Jasmine spec files).

In order to have the code more like a tutorial I have to omit some testing setup code.

Here is my source file: https://github.com/johnnywengluu/yobiengine-statemachine/blob/master/spec/Statemachine.spec.coffee

I have added @ignore to sections I don't want to show in the final output.

Here is the result: http://yiesm.nodejitsu.com/

As you can see the result is really great since you won't bloat the doc with all unnecessary setup code you don't want the user to see. For this case I have managed to turn a test spec to a tutorial. No need to separate them and have to manually keep them in sync and have an outdated tutorial that won't work. This is why a lot of coders don't have good documentation. It's pain in the ass work.

This will hopefully be one of the tools to end that, thanks to Docco and Jasmine.

I have added some lines in the coffee source file and then generated the js file. Then I regenerated the documentation.

You can just accept the added lines in .coffee source file and regenerate the js and doc file yourself.

Hope you will merge this. I showed this for another Docco lover and he loved the fact that he could turn specs into tutorials! Would also be good for people who want to hide some code from the documentation.

Johnny