We just tried compodoc for creating our Angular 4 App’s Code Documentation. My team is pretty happy with following features, it brings to table:
Features:
- Documentation Coverage
- Powerful Search based on lunr.js
- JSDoc support
- Minimalistic design
- Opensource. Available on NPM. MIT Licenced.
Problems:
I am writing this short blog post here to save you some time with issues, I faced while setting up compodoc. You are very welcome. :D
Following version of compodoc were found to be problematic:
- v0.0.1
- v0.0.41
One of those versions was not correctly parsing our component files so documentation was not getting generated for most of .ts files, while the other was running into issues like following after processing for more than ~15 minutes for a relatively not so large project.
compodoc/dist/index-cli.js:960
index: JSON.stringify(_this.getSearchIndex()),
^
RangeError: Invalid string lengthat JSON.stringify (<anonymous>)
at /Users/uajmal/work/nsx/mp/ui-ng/nsxt/node_modules/compodoc/dist/index-cli.js:960:37
at /Users/uajmal/work/nsx/mp/ui-ng/nsxt/node_modules/graceful-fs/graceful-fs.js:78:16
at tryToString (fs.js:425:3)
at FSReqWrap.readFileAfterClose [as oncomplete] (fs.js:412:12)
Another problem I faced with those versions was with its-d flag which is suppose to output your documentation files to a specified directory. It didn’t work as expected as I saw some documentation files being dumped in my app’s root directory while others were output in the specified directory. I have a bug filed for it here. My recommendation is to not use -d flag until the bug is resolved and find your documentation in directory ~/<your-app-root>/documentation/.
Solution:
Finally, found out that compodoc has now moved to @compodoc/compodoc where latest version (at the time of writing this article) was v1.0.1.
Version 1.0.1 worked like a charm creating just the output, I was expecting with all features properly working.
Here is how you can quickly get your compodoc working for you.
Add following to your package.json
"scripts": {
.
.
.
"compodoc": "./node_modules/.bin/compodoc -p ./src/tsconfig.app.json"}
.
.
"devDependencies": {
.
.
.
"@compodoc/compodoc": "1.0.1"
}
where tsconfig.app.json is your typescript configuration file for your app. You may create it yourself if it doesn’t exist or try to look for tsconfig.json instead.
Checkout this example tsconfig, if you like. My tsconfig.app.json have following JSON blobs, beside other key-value pairs mentioned in the example so you may like to use them as well.
include should include the files you specify. Don’t worry about ignoring *.spec.ts. Compodoc is smart to ignore those by itself. ** recursively searches through directories. Useexclude to exclude any directory.
{
.
.
.
"include": [
"src/**/*"
],
"exclude": [
"node_modules/"
]
}Required Improvements
@vogloblinsky and other contributors have done an amazing job. It will be nice to see following features in upcoming versions:
- Code coverage has this column which says something like 6/12 but it doesn’t mention what exactly is 12. It will be helpful to let the engineer know which comments are missing from his code.
- Ability to show how a component will look like in real life
- Support for documenting Test Coverage as well
