KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

inch_ex

★ 212 Open GitHub ↗

Provides a Mix task that gives you hints where to improve your inline docs.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Inch for Elixir [![Inline docs](http://inch-ci.org/github/rrrene/inch_ex.svg?branch=master)](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.

## 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, "~> 2.0", 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):  █  ▁ ▄ ▄
```

To get more information, use `explain`:

```bash
$ mix inch explain Foo.complicated/5

# Foo.complicated/5
┃ lib/foo.ex:53
┃ -----------------------------------------------------------------------
┃ Has documentation                                        50     0
┃ Has multiple code examples                               25     0
┃ Misses mentioning function parameter `line`             (20)    0
┃ Misses mentioning function parameter `max_length`       (20)    0
┃ -----------------------------------------------------------------------
┃ Score (min: 0, max: 100)                                 75     0
┃

```

## 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.

inch_ex

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README