RuleDocs is library designed to assist in automating documenting software that heavily uses Inversion of Control (IoC) and Dependency Injection (DI). It works by allowing the documentation to be easily internalized in the code, but also be easily extracted and placed in to a comma separated value format (CSV).
The inspiration for this code was a situation where management would would ask for updated documentation for some heavily IoC based rules systems. Updating the documentation required a developer to walk through the code, and verify any changes made in the code were also made in the documentation. This process was slow, tedious, and error prone.
Another common issue is that the documentation for software is often kept in a system completely separate from the development environment. This means the developer needs to remember to go update that external system as well.
###What RuleDocs can give you RuleDocs was written with some specific goals in mind:
- A consistent interface to work with documentation.
- Relevant documentation about the code is kept with the code.
- A developer may easily update the documentation when updating the code, since the documentation is right there.
- Documentation may easily be reviewed during code reviews.
- Automated build systems may now extract the documentation and use it to create external documentation.
###What RuleDocs does not do It does not create a CSV file. It only gives you the ability to extract CSV ready data. Writing it to a file or inserting the data into a database is beyond RuleDocs' scope. The decision for where the data's ultimate location depends on the build admin and / or management.
##QuickExample A short example of the output that RuleDocs will produce.
##IDocumented The interface required by RuleDocs to generate documentation; as well as a minimal list of methods needed to create the documentation.
##Example A more detailed example of generating documentation.
##RuleData An overview of the RuleData class.
##Formatter An overview of the Formatter class.
##Best Practices A few best practices I have learned from over the years regarding this type of documentation.