{"id":13483923,"url":"https://github.com/rrrene/inch","last_synced_at":"2025-05-15T08:06:00.195Z","repository":{"id":13137371,"uuid":"15819557","full_name":"rrrene/inch","owner":"rrrene","description":"A documentation analysis tool for the Ruby language","archived":false,"fork":false,"pushed_at":"2024-01-12T14:02:17.000Z","size":6621,"stargazers_count":520,"open_issues_count":0,"forks_count":40,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-07T02:19:51.524Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://rrrene.github.io/inch/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rrrene.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-01-11T08:49:09.000Z","updated_at":"2025-03-31T00:18:03.000Z","dependencies_parsed_at":"2024-06-18T13:37:21.478Z","dependency_job_id":"1a69e65b-bfb5-4835-b33c-72ed2a53ef86","html_url":"https://github.com/rrrene/inch","commit_stats":{"total_commits":656,"total_committers":15,"mean_commits":"43.733333333333334","dds":"0.17987804878048785","last_synced_commit":"6a07e32652a476c50cbff95eed927ebfc7a5c25f"},"previous_names":[],"tags_count":86,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrrene%2Finch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrrene%2Finch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrrene%2Finch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrrene%2Finch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rrrene","download_url":"https://codeload.github.com/rrrene/inch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248870144,"owners_count":21174989,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T17:01:16.904Z","updated_at":"2025-04-14T11:25:26.233Z","avatar_url":"https://github.com/rrrene.png","language":"Ruby","funding_links":[],"categories":["Documentation"],"sub_categories":[],"readme":"# Inch [![Build Status](https://travis-ci.org/rrrene/inch.svg?branch=master)](https://travis-ci.org/rrrene/inch) [![Code Climate](https://codeclimate.com/github/rrrene/inch.svg)](https://codeclimate.com/github/rrrene/inch) [![Inline docs](http://inch-ci.org/github/rrrene/inch.svg)](http://inch-ci.org/github/rrrene/inch)\n\n`inch` gives you hints where to improve your docs. One Inch at a time.\n\nTake a look at the [project page with screenshots (live and in full color)](http://rrrene.github.io/inch/).\n\n## What can it do?\n\n`inch` is a little bit like Code Climate, but for your inline code documentation (and not a webservice).\n\nIt is a command-line utility that suggests places in your codebase where documentation can be improved.\n\nIf there are no inline-docs yet, `inch` can tell you where to start.\n\n\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'inch', require: false\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install inch\n\n\n\n## Usage\n\nTo run Inch, simply type\n\n    $ inch\n\nGiven a `lib` directory with the following code inside:\n\n```ruby\nclass Foo\n  # A complicated method\n  def complicated(o, i, *args, \u0026block)\n    # ... snip ...\n  end\n\n  # An example of a method that takes a parameter (+param1+)\n  # and does nothing.\n  #\n  # Returns nil\n  def nothing(param1)\n  end\n\n  def filename\n    \"#{self.class}_#{id}.foo\"\n  end\nend\n```\n\nInch will suggest that the docs could be improved:\n\n    # Properly documented, could be improved:\n\n    ┃  B  ↑  Foo#complicated\n\n    # Undocumented:\n\n    ┃  U  ↑  Foo\n    ┃  U  ↗  Foo#filename\n\n    You might want to look at these files:\n\n    ┃ lib/foo.rb\n\n    Grade distribution (undocumented, C, B, A):  █  ▁ ▄ ▄\n\n    Only considering priority objects: ↑ ↗ →  (use `--help` for options).\n\n\n\n## Configuration\n\nBy default, Inch looks into `{app,lib}/**/*.rb` for Ruby source files. You can customize this by either passing the desired files to the executable:\n\n    $ inch suggest plugins/**/*.rb\n\nor by creating a file named `.inch.yml` in your project directory:\n\n```yaml\nfiles:\n  # define files included in the analysis (defaults to [\"{app,lib}/**/*.rb\"])\n  included:\n    - plugins/**/*.rb\n  # define files excluded from the analysis (defaults to [])\n  excluded:\n    # you can use file paths\n    - plugins/vendor/sparkr/sparkr.rb\n    # or globs\n    - plugins/vendor/**/*.rb\n    # or regular expressions\n    - !ruby/regexp /vendor/\n```\n\nAs you would expect, `included` sets an array of included files (or globs) and `excluded` sets an array of files, globs or regexes of files to exclude from the evaluation.\n\n\n## Philosophy\n\nInch 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.\n\n* It does not aim for \"fully documented\" or \"100% documentation coverage\".\n* It does not tell you to document all your code (neither does it tell you not to).\n* It does not impose rules on how your documentation should look like.\n* 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\".\n\nInch takes a more relaxed approach towards documentation measurement and tries to show you places where your codebase *could* use more documentation.\n\n\n\n### The Grade System\n\nInch assigns grades to each class, module, constant or method in a codebase, based on how complete the docs are.\n\nThe grades are:\n\n* `A` - Seems really good\n* `B` - Properly documented, but could be improved\n* `C` - Needs work\n* `U` - Undocumented\n\nUsing this system has some advantages compared to plain coverage scores:\n\n* You can get an `A` even if you \"only\" get 90 out of 100 possible points.\n* Getting a `B` is basically good enough.\n* Undocumented objects are assigned a special grade, instead of scoring 0%.\n\nThe 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.\n\n\n\n### Priorities ↑ ↓\n\nEvery class, module, constant and method in a codebase is assigned a priority which reflects how important Inch thinks it is to be documented.\n\nThis process follows some reasonable rules, like\n\n* it is more important to document public methods than private ones\n* it is more important to document methods with many parameters than methods without parameters\n* it is not important to document objects marked as `:nodoc:`\n\nPriorities are displayed as arrows. Arrows pointing north mark high priority objects, arrows pointing south mark low priority objects.\n\n\n\n### No overall scores or grades\n\nInch does not give you a grade for your whole codebase.\n\n\"Why?\" you might ask. Look at the example below:\n\n    Grade distribution (undocumented, C, B, A):  ▄  ▁ ▄ █\n\nIn this example there is a part of code that is still undocumented, but\nthe vast majority of code is rated A or B.\n\nThis tells you three things:\n\n* There is a significant amount of documentation present.\n* The present documentation seems good.\n* There are still undocumented methods.\n\nInch does not really tell you what to do from here. It suggests objects and\nfiles that could be improved to get a better rating, but that is all. This\nway, it is perfectly reasonable to leave parts of your codebase\nundocumented.\n\nInstead of reporting\n\n    coverage: 67.1%  46 ouf of 140 checks failed\n\nand leaving you with a bad feeling, Inch tells you there are still\nundocumented objects without judging.\n\nThis 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).\n\nThe grade distribution does a much better job of painting the bigger picture.\n\n\n\n## Features\n\nInch is built to parse [YARD](http://yardoc.org/),\n[RDoc](http://rdoc.rubyforge.org/) and [TomDoc](http://tomdoc.org/)\nstyle documentation comments, but works reasonably well with unstructured\ncomments.\n\nThese inline-docs below all score an `A` despite being written in different styles:\n\n```ruby\n# Detects the size of the blob.\n#\n# @example\n#   blob_size(filename, blob) # =\u003e some value\n#\n# @param filename [String] the filename\n# @param blob [String] the blob data\n# @param mode [String, nil] optional String mode\n# @return [Fixnum,nil]\ndef blob_size(filename, blob, mode = nil)\n```\n\n```ruby\n# Detects the size of the blob.\n#\n#   blob_size(filename, blob) # =\u003e some value\n#\n# Params:\n# +filename+:: String filename\n# +blob+:: String blob data\n# +mode+:: Optional String mode (defaults to nil)\ndef blob_size(filename, blob, mode = nil)\n```\n\n```ruby\n# Public: Detects the size of the blob.\n#\n# filename - String filename\n# blob - String blob data\n# mode - Optional String mode (defaults to nil)\n#\n# Examples\n#\n#   blob_size(filename, blob)\n#   # =\u003e some value\n#\n# Returns Fixnum or nil.\ndef blob_size(filename, blob, mode = nil)\n```\n\n\nBut you don't have to adhere to any specific syntax. This gets an `A` as well:\n\n```ruby\n# Returns the size of a +blob+ for a given +filename+.\n#\n#   blob_size(filename, blob)\n#   # =\u003e some value\n#\ndef blob_size(filename, blob, mode = nil)\n```\n\nInch *let's you write your documentation the way you want*.\n\n\n## Subcommands\n\nIt comes with four sub-commands: `suggest`, `stats`, `show`, and `list`\n\n\n### inch suggest\n\nSuggests places where a codebase suffers a lack of documentation. The command\nline exit status will be above zero when suggestions are found.\n\n    $ inch suggest\n\n    # Properly documented, could be improved:\n\n    ┃  B  ↑  Inch::CLI::Command::BaseList#prepare_list\n    ┃  B  ↑  Inch::CodeObject::Ruby::MethodParameterObject#initialize\n    ┃  B  ↗  Inch::CLI::Command::Stats#run\n    ┃  B  ↗  Inch::CLI::CommandParser#run\n\n    # Not properly documented:\n\n    ┃  C  ↑  Inch::CodeObject::NodocHelper#implicit_nodoc_comment?\n    ┃  C  ↑  Inch::CLI::Command::Output::Suggest#initialize\n    ┃  C  ↑  Inch::Rake::Suggest#initialize\n\n    # Undocumented:\n\n    ┃  U  ↑  Inch::Evaluation::ConstantObject#evaluate\n    ┃  U  ↑  Inch::Evaluation::MethodObject#evaluate\n    ┃  U  ↑  Inch::SourceParser#find_object\n\n    You might want to look at these files:\n\n    ┃ lib/inch/code_object/proxy/base.rb\n    ┃ lib/inch/code_object/proxy/method_object.rb\n    ┃ lib/inch/evaluation/role/object.rb\n\n    Grade distribution (undocumented, C, B, A):  █  ▃ ▁ ▄\n\n    Only considering priority objects: ↑ ↗ →  (use `--help` for options).\n\n\n\n### inch stats\n\nShows you an overview of the codebase.\n\n    $ inch stats\n\n    Grade distribution: (undocumented, C, B, A)\n\n      Overall:  █  ▂ ▁ ▃    439 objects\n\n    Grade distribution by priority:\n\n            ↑   ▁  ▄ █ ▁     10 objects\n\n            ↗   █  ▃ ▁ ▃    302 objects\n\n            →   ▆  ▂ ▁ █     73 objects\n\n            ↘   █  ▁ ▁ ▁     54 objects\n\n            ↓   ▁  ▁ ▁ ▁      0 objects\n\n    Priority distribution in grades: (low to high)\n\n          ↓      ↘      →      ↗      ↑\n      U:  ▁ ▁ ▁ ▁ ▁ ▁ ▂ ▂ ▁ █ ▁ ▁ ▁ ▁ ▁   243 objects\n\n      C:  ▁ ▁ ▁ ▁ ▁ ▁ ▁ ▁ ▁ █ ▁ ▁ ▁ ▁ ▁    73 objects\n\n      B:  ▁ ▁ ▁ ▁ ▁ ▁ ▁ ▁ ▁ █ ▂ ▄ ▁ ▁ ▁    19 objects\n\n      A:  ▁ ▁ ▁ ▁ ▁ ▁ ▁ ▄ ▁ █ ▁ ▁ ▁ ▁ ▁   104 objects\n\n\n    Try `--format json|yaml` for raw numbers.\n\n\n\n### inch show\n\nShows you details about what can be improved in a specific object.\n\n    $ inch show Inch::SourceParser#find_object\n\n    # Inch::SourceParser#find_object\n\n    ┃ -\u003e lib/inch/source_parser.rb:16\n    ┃ ------------------------------------------------------\n    ┃ Grade: C - Needs work\n    ┃ ------------------------------------------------------\n    ┃ + Add a comment describing the method\n    ┃ + Describe the parameter 'path'\n    ┃ + Describe the return type of 'find_object'\n    ┃ + Add a code example (optional)\n    ┃ ------------------------------------------------------\n\n\n\n### inch list\n\nLists all objects in your codebase with their grades.\n\n    $ inch list\n\n    # Seems really good\n\n    ┃  A  ↑  Inch::CLI::Command::Output::Console#object\n    ┃  A  ↗  Inch::CodeObject::Proxy#depth\n    ┃  A  ↗  Inch::CLI::Command::Base#description\n    ┃  A  ↗  Inch::CodeObject::NodocHelper#nodoc?\n    ┃ ...  (omitting 75 objects)\n\n    # Proper documentation present\n\n    ┃  B  ↑  Inch::CLI::Command::Suggest#run\n    ┃  B  ↑  Inch::CodeObject::Ruby::MethodParameterObject#initialize\n    ┃  B  ↗  Inch::CLI::Command::Stats#run\n    ┃  B  ↗  Inch::CLI::CommandParser#run\n\n    # Needs work\n\n    ┃  C  ↑  Inch::CodeObject::NodocHelper#implicit_nodoc_comment?\n    ┃  C  ↑  Inch::CLI::Command::Output::Console#initialize\n    ┃  C  ↑  Inch::Evaluation::ConstantObject#evaluate\n    ┃  C  ↑  Inch::SourceParser#find_object\n    ┃ ...  (omitting 248 objects)\n\n    This output omitted 323 objects. Use `--all` to display all objects.\n\n\n\n### Rake task\n\nAdd this to your `Rakefile`:\n\n    require 'inch/rake'\n\n    Inch::Rake::Suggest.new\n\nThis creates a rake task named `inch`. Change the name by passing it to the constructor. Use the `args` config option to add any command-line arguments from `inch suggest --help`.\n\n    require 'inch/rake'\n\n    Inch::Rake::Suggest.new(\"doc:suggest\") do |suggest|\n      suggest.args \u003c\u003c \"--private\"\n    end\n\n\n\n\n\n## Limitations\n\nHow you document your code is up to you and Inch can't actually tell you how good your docs are.\n\nIt can't tell if your code examples work or if you described parameters\ncorrectly or if you have just added `# TODO: write docs` to each and every\nmethod.\n\nIt is just a tool, that you can use to find parts in your codebase that are\nlacking documentation.\n\n\n\n## How is this different from ...?\n\n### Documentation coverage\n\nDocumentation coverage checks (like they can be found in\n[cane](https://github.com/square/cane) and\n[rubocop](https://github.com/bbatsov/rubocop)) look at all code objects and\ndetermine if the found documentation meets a certain threshold/expectation.\n\nInch takes a different approach as it aims for \"properly documented\" rather\nthan \"100% coverage\".\n\n### Yardstick\n\n[Yardstick](https://github.com/dkubb/yardstick) is a tool that verifies\ndocumentation coverage of Ruby code and is specifically designed for\n[YARD-style documentation](http://yardoc.org/). It is a great tool to see\nwhere your docs could benefit from YARD's extra features over RDoc, but, at\nthe same time, it is very overwhelming when applied to a codebase that does\nnot yet adhere to YARD's standards.\n\nInch takes a less YARD specific, more \"relaxed\" approach: It recognizes\ndifferent forms of documentation (even in the same codebase) and assigns\ngrades instead of coverage measurements. So you can get an \"A\" rating without\nemploying every technique YARD has to offer.\n\n\n\n## Contributing\n\n1. [Fork it!](http://github.com/rrrene/inch/fork)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n\n\n## Author\n\nRené Föhring (@rrrene)\n\n\n\n## Credits\n\nInch would not exist without Loren Segal's [YARD](http://yardoc.org/).\n\n\n\n## License\n\nInch is released under the MIT License. See the LICENSE file for further\ndetails.\n\nFor YARD's licensing, see YARD's README under http://yardoc.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrrene%2Finch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frrrene%2Finch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrrene%2Finch/lists"}