# Inch for Elixir [](http://inch-ci.org/github/rrrene/inch_ex)
Inch for Elixir provides a Mix task to give you hints where to improve your inline docs. One Inch at a time.
[Inch CI](http://inch-ci.org) is the corresponding web service that provides continuous coverage analysis for open source projects.
## What can it do?
Inch for Elixir is a utility that suggests places in your codebase where documentation can be improved.
If there are no inline-docs yet, Inch for Elixir can tell you where to start.
## Installation
Add Inch for Elixir as a dependency in your `mix.exs` file.
```elixir
defp deps do
[
{:inch_ex, github: "rrrene/inch_ex", only: [:dev, :test]}
]
end
```
After you are done, run this in your shell to fetch the new dependency:
$ mix deps.get
## Usage
To run Inch, simply type
$ mix inch
and you will get something like the following:
```bash
$ mix inch
# Properly documented, could be improved:
┃ B ↑ Foo.complicated/5
# Undocumented:
┃ U ↑ Foo
┃ U ↗ Foo.filename/1
Grade distribution (undocumented, C, B, A): █ ▁ ▄ ▄
```
## Philosophy
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.
* It does not aim for "fully documented" or "100% documentation coverage".
* It does not tell you to document all your code (neither does it tell you not to).
* It does not impose rules on how your documentation should look like.
* It does not require that, e.g."every method's documentation should be a single line under 80 characters not ending in a period" or that "every class and module should provide a code example of their usage".
Inch takes a more relaxed approach towards documentation measurement and tries to show you places where your codebase *could* use more documentation.
### The Grade System
Inch assigns grades to each module, function, macro or callback in a codebase, based on how complete the docs are.
The grades are:
* `A` - Seems really good
* `B` - Properly documented, but could be improved
* `C` - Needs work
* `U` - Undocumented
Using this system has some advantages compared to plain coverage scores:
* You can get an `A` even if you "only" get 90 out of 100 possible points.
* Getting a `B` is basically good enough.
* Undocumented objects are assigned a special grade, instead of scoring 0%.
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.
### Priorities ↑ ↓
Every class, module, constant and method 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
* it is more important to document public methods than private ones
* it is more important to document methods with many parameters than methods without parameters
* it is not important to document objects marked as `@doc false`
Priorities are displayed as arrows. Arrows pointing north mark high priority objects, arrows pointing south mark low priority objects.
### No overall scores or grades
Inch does not give you a grade for your whole codebase.
"Why?" you might ask. Look at the example below:
Grade distribution (undocumented, C, B, A): ▄ ▁ ▄ █
In this example there is a part of code that is still undocumented, but
the vast majority of code is rated A or B.
This tells you three things:
* There is a significant amount of documentation present.
* The present documentation seems good.
* There are still undocumented methods.
Inch does not really tell you what to do from here. It suggests objects and
files that could be improved to get a better rating, but that is all. This
way, it is perfectly reasonable to leave parts of your codebase
undocumented.
Instead of reporting
coverage: 67.1% 46 ouf of 140 checks failed
and leaving you with a bad feeling, Inch tells you there are still
undocumented objects without judging.
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.
## Further information
I will point you to the [Inch for Ruby README](https://github.com/rrrene/inch#philosophy) for more information about the Inch project.
## Contributing
1. [Fork it!](http://github.com/rrrene/inch_ex/fork)
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
## Author
René Föhring (@rrrene)
## Credits
The first version of Inch for Elixir owed its existence to the extensive study and "code borrowing" from ExDoc.
## License
Inch for Elixir is released under the MIT License. See the LICENSE file for further
details.
