Quickstart
Install via NPM:
Try it out (showing output for Watai):
Inch is a command-line tool that gives you hints where to improve your docs.
One Inch at a time.
Install via NPM:
Try it out (showing output for Watai):
Inch is a command-line tool that gives you hints where to improve your docs.
One Inch at a time.
Inch was created to help people document their code, therefore it may be more important to look at what it does not do than at what it does.
Inch takes a more relaxed approach towards documentation measurement and tries to show you places where your codebase could use more documentation.
Inch assigns grades to each class, module, constant or function in a codebase, based on how complete the docs are.
The grades are:
A
- Seems really goodB
- Properly documented, but could be improvedC
- Needs workU
- UndocumentedUsing this system has some advantages compared to plain coverage scores:
A
even if you "only" get 90 out of 100 possible points.B
is basically good enough.The last point might be the most important one: If objects are undocumented, there is nothing to evaluate. Therefore you can not simply give them a bad rating, because they might be left undocumented intentionally.
Inch does not give you a grade for your whole codebase.
"Why?" you might ask. Look at the example above.
You can see a grade distribution that tells you three things:
This provides a lot more insight than an overall grade could, because an overall grade for the above example would either be an A
(if the evaluation ignores undocumented objects) or a weak C
(if the evaluation includes them).
The grade distribution does a much better job of painting the bigger picture.
Every class, module and function in a codebase is assigned a priority which reflects how important Inch thinks it is to be documented.
This process follows some reasonable rules, like
// @private
Priorities are displayed as arrows. Arrows pointing north mark high priority objects, arrows pointing south mark low priority objects.
Inch is build to parse JSDoc, AtomDoc and TomDoc style documentation comments, but works reasonably well with unstructured comments.
These inline-docs below all score an A
despite being written in different styles:
/**
* Detects the size of the blob.
*
* @example
* getBlobSize(filename, blob) * => some value
*
* @param filename {String} the filename
* @param blob {String} the blob data
* @param mode {String, null} optional String mode
* @return {Number, null}
*/
var getBlobSize = function(filename, blob, mode) { }
/**
* Public: Detects the size of the blob.
*
* * `count` {Number} representing count
*
* * `filename` {String} the filename
* * `blob` {String} the blob data
* * `mode` {String,null} optional String mode
*
* ## Example
*
* getBlobSize(filename, blob) * => some value
*
* Returns Number or null.
*/
var getBlobSize = function(filename, blob, mode) { }
// Public: Detects the size of the blob.
//
// filename - String filename
// blob - String blob data
// mode - Optional String mode (defaults to null)
//
// Examples
//
// getBlobSize(filename, blob)
// // => some value
//
// Returns Number or null.
var getBlobSize = function(filename, blob, mode) { }
But you don't have to adhere to any specific syntax. This gets an A
as well:
// Returns the size of a +blob+ for a given +filename+ (+mode+ is optional).
//
// getBlobSize(filename, blob)
// // => some value
//
var getBlobSize = function(filename, blob, mode = null)
Inch let's you write your documentation the way you want.
Inch is available via NPM. The source code is published on GitHub.
You can find more information on subcommands, limitations, and a comparison with other tools in the README on GitHub.