You’ll have to document your app. First you’ll have to describe what it should do (via RSpec), and then how it does (using doc & diagram generator plugins).
RSpec is the most elegant way to describe the REQUIREMENT SPECIFICATION for your app. And contains a basic testing framework to quickly test your app against these rspecs. Lovely.
There some golden rules to follow in testing & documenting your app:
- Test & specify & document only the code you write. Trust your rails core and your installed plugins, don’t bother testing them. Anyway RSpec is a generator, when you generate models/controllers with other plugins (ex. AAA, Authentication, Streamlined, …) you’ll use the plugins’ own generator instead of /script/generate rspec_scaffold
- Document every bit of code you write . It is easy: before you write code always start with a comment.
And don’t forget to use these tools, again, heavily:
- RSpec for specs creation and basic testing (includes RCov, a coverage testing tool)
- rake:doc to collect your comments from the code you write and to generate a quick manual for you.
- RailRoad or Rails Application Visualizer to generate the diagrams of your models (db, controllers)
- rake:stats to get your statistics like LOC/KLOC etc.
However there are some drawbacks with all these above: none of them even combined will give you the right documentation.
- Rspec is too verbose by default, I mean when generating resources with script/generate rspec_ the generator automatically creates lots of default specs which are not interesting for you. It is against the 1st rule: test&document only what you write, in rest trust your vendors. For example, without writing any specs at the first rake spec:doc I got around 100 default specs for my 3 resources, none of them interesting for me. What if I’ll generate 10-20 other resources? I’ll get by default around a few hundreds of non interesting specs. In this case how I’ll find easily my own specs?
- rake:doc is very oldschool. It is almost useless if you want to collect all your comments from code into a usable documentation. Deals only with methods, if you add other comments in your code they will be completely ignored. For example if a controller uses a layout. Or if the CRUD actions are taken over by ActiveScaffold.
So … I’ll have to find solutions to achieve my goal: deal (= test + doc) only with the code I write, ignore the rest.
