{"id":13533108,"url":"https://github.com/zverok/yard-junk","last_synced_at":"2025-06-16T08:34:00.191Z","repository":{"id":51450425,"uuid":"101503541","full_name":"zverok/yard-junk","owner":"zverok","description":"Get rid of the junk in your YARD docs","archived":false,"fork":false,"pushed_at":"2024-09-08T12:59:17.000Z","size":138,"stargazers_count":72,"open_issues_count":16,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-25T07:17:03.618Z","etag":null,"topics":["ci","docs","ruby","yard"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zverok.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":null,"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":"2017-08-26T18:01:10.000Z","updated_at":"2025-04-24T19:02:46.000Z","dependencies_parsed_at":"2024-06-18T22:48:05.006Z","dependency_job_id":"f1710ae1-3849-40c8-b86e-ece42d080a6a","html_url":"https://github.com/zverok/yard-junk","commit_stats":{"total_commits":112,"total_committers":4,"mean_commits":28.0,"dds":0.1964285714285714,"last_synced_commit":"a864a2b314fb72e8a624fab214ec2b76d552f61c"},"previous_names":["zverok/junk_yard"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/zverok/yard-junk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zverok%2Fyard-junk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zverok%2Fyard-junk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zverok%2Fyard-junk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zverok%2Fyard-junk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zverok","download_url":"https://codeload.github.com/zverok/yard-junk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zverok%2Fyard-junk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260126642,"owners_count":22962668,"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":["ci","docs","ruby","yard"],"created_at":"2024-08-01T07:01:16.627Z","updated_at":"2025-06-16T08:34:00.168Z","avatar_url":"https://github.com/zverok.png","language":"Ruby","funding_links":[],"categories":["Ruby","Awesome Ruby CLIs"],"sub_categories":["Linting"],"readme":"# Yard-Junk: get rid of junk in your YARD docs!\n\n[![Gem Version](https://badge.fury.io/rb/yard-junk.svg)](http://badge.fury.io/rb/yard-junk)\n![Build Status](https://github.com/zverok/yard-junk/workflows/CI/badge.svg?branch=master)\n\nYard-Junk is [yard](https://github.com/lsegal/yard) plugin/patch, that provides:\n\n* structured documentation error logging;\n* documentation errors validator, ready to be integrated into CI pipeline.\n\n## Showcase\n\nLet's generate the docs for the [rom](https://github.com/rom-rb/rom) library.\n\n\u003cdetails\u003e\u003csummary\u003eOutput of `yard doc` without JunkYard\u003c/summary\u003e\n\n```\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Types\n\tin file 'core/lib/rom/types.rb':9:\n\n\t9: include Dry::Types.module\n\n[warn]: Invalid tag format for @example in file `core/lib/rom/global.rb` near line 41\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Schema\n\tin file 'core/lib/rom/schema.rb':66:\n\n\t66: include Dry::Equalizer(:name, :attributes, :associations)\n\n[warn]: @param tag has unknown parameter name:\n    in file `core/lib/rom/schema.rb' near line 149\n[warn]: @param tag has unknown parameter name:\n    in file `core/lib/rom/schema.rb' near line 305\n[warn]: @param tag has unknown parameter name:\n    in file `core/lib/rom/schema.rb' near line 316\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Command\n\tin file 'core/lib/rom/command.rb':30:\n\n\t30: include Dry::Equalizer(:relation, :options)\n\n[warn]: @param tag has unknown parameter name: Transaction\n    in file `core/lib/rom/gateway.rb' near line 176\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Pipeline::Composite\n\tin file 'core/lib/rom/pipeline.rb':82:\n\n\t82: include Dry::Equalizer(:left, :right)\n\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Registry\n\tin file 'core/lib/rom/registry.rb':13:\n\n\t13: include Dry::Equalizer(:elements)\n\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Relation\n\tin file 'core/lib/rom/relation.rb':129:\n\n\t129: include Dry::Equalizer(:name, :dataset)\n\n[warn]: @param tag has unknown parameter name: options\n    in file `core/lib/rom/relation.rb' near line 302\n[warn]: @param tag has unknown parameter name: new_options\n    in file `core/lib/rom/relation.rb' near line 411\n[warn]: @param tag has unknown parameter name: klass\n    in file `core/lib/rom/relation.rb' near line 529\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Attribute\n\tin file 'core/lib/rom/attribute.rb':17:\n\n\t17: include Dry::Equalizer(:type, :options)\n\n[warn]: @param tag has unknown parameter name:\n    in file `core/lib/rom/attribute.rb' near line 344\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Container\n\tin file 'core/lib/rom/container.rb':101:\n\n\t101: include Dry::Equalizer(:gateways, :relations, :mappers, :commands)\n\n[warn]: @param tag has unknown parameter name: base\n    in file `core/lib/rom/plugin_base.rb' near line 41\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Commands::Lazy\n\tin file 'core/lib/rom/commands/lazy.rb':10:\n\n\t10: include Dry::Equalizer(:command, :evaluator)\n\n[warn]: @param tag has unknown parameter name: The\n    in file `core/lib/rom/configuration.rb' near line 50\n[warn]: @param tag has unknown parameter name: Plugin\n    in file `core/lib/rom/configuration.rb' near line 50\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Relation::Name\n\tin file 'core/lib/rom/relation/name.rb':17:\n\n\t17: include Dry::Equalizer(:relation, :dataset)\n\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Commands::Graph\n\tin file 'core/lib/rom/commands/graph.rb':12:\n\n\t12: include Dry::Equalizer(:root, :nodes)\n\n[warn]: @param tag has unknown parameter name: names\n    in file `core/lib/rom/memory/dataset.rb' near line 61\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Relation::Graph\n\tin file 'core/lib/rom/relation/graph.rb':29:\n\n\t29: include Dry::Equalizer(:root, :nodes)\n\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::PluginRegistryBase\n\tin file 'core/lib/rom/plugin_registry.rb':88:\n\n\t88: include Dry::Equalizer(:elements, :plugin_type)\n\n[warn]: Unknown tag @raises in file `core/lib/rom/plugin_registry.rb` near line 143\n[warn]: Unknown tag @raises in file `core/lib/rom/plugin_registry.rb` near line 190\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Relation::Loaded\n\tin file 'core/lib/rom/relation/loaded.rb':12:\n\n\t12: include Dry::Equalizer(:source, :collection)\n\n[warn]: Unknown tag @raises in file `core/lib/rom/relation/loaded.rb` near line 94\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Schema::Inferrer\n\tin file 'core/lib/rom/schema/inferrer.rb':27:\n\n\t27: include Dry::Equalizer(:options)\n\n[warn]: @param tag has unknown parameter name: name\n    in file `core/lib/rom/command_registry.rb' near line 57\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Relation::Curried\n\tin file 'core/lib/rom/relation/curried.rb':22:\n\n\t22: include Dry::Equalizer(:relation, :options)\n\n[warn]: Unknown tag @raises in file `core/lib/rom/relation/curried.rb` near line 72\n[warn]: @param tag has unknown parameter name: adapter\n    in file `core/lib/rom/global/plugin_dsl.rb' near line 42\n[warn]: @param tag has unknown parameter name:\n    in file `core/lib/rom/relation/combined.rb' near line 33\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Associations::Abstract\n\tin file 'core/lib/rom/associations/abstract.rb':17:\n\n\t17: include Dry::Equalizer(:definition, :source, :target)\n\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Notifications::Event\n\tin file 'core/lib/rom/support/notifications.rb':75:\n\n\t75: include Dry::Equalizer(:id, :payload)\n\n[warn]: @param tag has unknown parameter name: command\n    in file `core/lib/rom/commands/class_interface.rb' near line 86\n[warn]: @param tag has unknown parameter name: parent\n    in file `core/lib/rom/commands/class_interface.rb' near line 86\n[warn]: @param tag has unknown parameter name: options\n    in file `core/lib/rom/commands/class_interface.rb' near line 112\n[warn]: @param tag has unknown parameter name:\n    in file `core/lib/rom/commands/class_interface.rb' near line 123\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Commands::Graph::InputEvaluator\n\tin file 'core/lib/rom/commands/graph/input_evaluator.rb':5:\n\n\t5: include Dry::Equalizer(:tuple_path, :excluded_keys)\n\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Associations::Definitions::Abstract\n\tin file 'core/lib/rom/associations/definitions/abstract.rb':16:\n\n\t16: include Dry::Equalizer(:source, :target, :result)\n\n[warn]: @param tag has unknown parameter name: options\n    in file `core/lib/rom/associations/definitions/abstract.rb' near line 74\n[warn]: @param tag has unknown parameter name: options\n    in file `changeset/lib/rom/changeset.rb' near line 84\n[warn]: in YARD::Handlers::Ruby::ClassHandler: Undocumentable superclass (class was added without superclass)\n\tin file 'changeset/lib/rom/changeset/pipe.rb':28:\n\n\t28: class Pipe \u003c Transproc::Transformer[PipeRegistry]\n\n[warn]: @param tag has unknown parameter name: assoc\n    in file `changeset/lib/rom/changeset/stateful.rb' near line 222\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Header\n\tin file 'mapper/lib/rom/header.rb':12:\n\n\t12: include Dry::Equalizer(:attributes, :model)\n\n[warn]: @param tag has unknown parameter name: model\n    in file `mapper/lib/rom/header.rb' near line 52\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Mapper\n\tin file 'mapper/lib/rom/mapper.rb':11:\n\n\t11: include Dry::Equalizer(:transformers, :header)\n\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Header::Attribute\n\tin file 'mapper/lib/rom/header/attribute.rb':14:\n\n\t14: include Dry::Equalizer(:name, :key, :type)\n\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Header::Embedded\n\tin file 'mapper/lib/rom/header/attribute.rb':110:\n\n\t110: include Dry::Equalizer(:name, :key, :type, :header)\n\n[warn]: @param tag has unknown parameter name:\n    in file `mapper/lib/rom/processor/transproc.rb' near line 215\n[warn]: in YARD::Handlers::Ruby::MixinHandler: Undocumentable mixin: YARD::Parser::UndocumentableError for class ROM::Session\n\tin file 'repository/lib/rom/repository/session.rb':8:\n\n\t8: include Dry::Equalizer(:queue, :status)\n\n[warn]: The proxy Coercible has not yet been recognized.\nIf this class/method is part of your source tree, this will affect your documentation results.\nYou can correct this issue by loading the source file for this object before `core/lib/rom/types.rb'\n\n[warn]: The proxy Coercible has not yet been recognized.\nIf this class/method is part of your source tree, this will affect your documentation results.\nYou can correct this issue by loading the source file for this object before `core/lib/rom/types.rb'\n\n[warn]: The proxy Coercible has not yet been recognized.\nIf this class/method is part of your source tree, this will affect your documentation results.\nYou can correct this issue by loading the source file for this object before `core/lib/rom/types.rb'\n```\n\u003c/details\u003e\n\nThings to notice:\n\n* irregular and frequently approximate addresses (`in file 'core/lib/rom/types.rb':9`,\n  `in file 'core/lib/rom/global.rb' near line 41`, sometimes in separate line, sometimes inline),\n  hard to jump-to with any tool;\n* a lot of ununderstood metaprogramming (grep for \"Undocumentable mixin\") -- nothing to fix here,\n  but YARD still notifies you;\n* verbose and not very informative errors (look at that \"Undocumentable mixin\" -- and then grep\n  for \"The proxy Coercible has not yet been recognized.\" and compare).\n\n\u003cdetails\u003e\u003csummary\u003eOutput of `yard doc` with Yard-Junk\u003c/summary\u003e\n\n```\ncore/lib/rom/global.rb:40: [InvalidTagFormat] Invalid tag format for @example\ncore/lib/rom/schema.rb:144: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/schema.rb:300: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/schema.rb:311: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/gateway.rb:171: [UnknownParam] @param tag has unknown parameter name: Transaction\ncore/lib/rom/relation.rb:297: [UnknownParam] @param tag has unknown parameter name: options\ncore/lib/rom/relation.rb:406: [UnknownParam] @param tag has unknown parameter name: new_options\ncore/lib/rom/relation.rb:524: [UnknownParam] @param tag has unknown parameter name: klass\ncore/lib/rom/attribute.rb:339: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/plugin_base.rb:38: [UnknownParam] @param tag has unknown parameter name: base. Did you mean `_base`?\ncore/lib/rom/configuration.rb:46: [UnknownParam] @param tag has unknown parameter name: The\ncore/lib/rom/configuration.rb:47: [UnknownParam] @param tag has unknown parameter name: Plugin. Did you mean `plugin`?\ncore/lib/rom/memory/dataset.rb:54: [UnknownParam] @param tag has unknown parameter name: names\ncore/lib/rom/plugin_registry.rb:140: [UnknownTag] Unknown tag @raises. Did you mean @raise?\ncore/lib/rom/plugin_registry.rb:187: [UnknownTag] Unknown tag @raises. Did you mean @raise?\ncore/lib/rom/relation/loaded.rb:91: [UnknownTag] Unknown tag @raises. Did you mean @raise?\ncore/lib/rom/command_registry.rb:52: [UnknownParam] @param tag has unknown parameter name: name\ncore/lib/rom/relation/curried.rb:69: [UnknownTag] Unknown tag @raises. Did you mean @raise?\ncore/lib/rom/global/plugin_dsl.rb:41: [UnknownParam] @param tag has unknown parameter name: adapter\ncore/lib/rom/relation/combined.rb:28: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/commands/class_interface.rb:78: [UnknownParam] @param tag has unknown parameter name: command\ncore/lib/rom/commands/class_interface.rb:79: [UnknownParam] @param tag has unknown parameter name: parent\ncore/lib/rom/commands/class_interface.rb:108: [UnknownParam] @param tag has unknown parameter name: options. Did you mean `_options`?\ncore/lib/rom/commands/class_interface.rb:118: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/associations/definitions/abstract.rb:66: [UnknownParam] @param tag has unknown parameter name: options\nchangeset/lib/rom/changeset.rb:79: [UnknownParam] @param tag has unknown parameter name: options. Did you mean `new_options`?\nchangeset/lib/rom/changeset/stateful.rb:219: [UnknownParam] @param tag has unknown parameter name: assoc\nmapper/lib/rom/header.rb:47: [UnknownParam] @param tag has unknown parameter name: model\nmapper/lib/rom/processor/transproc.rb:212: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/types.rb:1: [UnknownNamespace] namespace Coercible is not recognized\ncore/lib/rom/types.rb:1: [UnknownNamespace] namespace Coercible is not recognized\ncore/lib/rom/types.rb:1: [UnknownNamespace] namespace Coercible is not recognized\n```\n\u003c/details\u003e\n\nThings to notice:\n\n* Regular output style with clearly recognizable addresses (and fixed to point at actual line with\n  the problematic tag, not the method which tag is related for);\n* Error classes, allowing grouping, grepping, and configuring (notice no \"Undocumentable xxx\" errors:\n  I've just configured `yard-junk` to drop them for this repo);\n* Usage of Ruby's bundled `did_you_mean` gem to show reasonable suggestions:\n```\nUnknown tag @raises. Did you mean @raise?\n@param tag has unknown parameter name: options. Did you mean `new_options`?\n```\n* Rephrased and cleaned up messages.\n\n\u003cdetails\u003e\u003csummary\u003e`yard-junk` tool output\u003c/summary\u003e\n\n```\nProblems\n--------\nmistyped tags or other typos in documentation\n\nchangeset/lib/rom/changeset.rb:79: [UnknownParam] @param tag has unknown parameter name: options. Did you mean `new_options`?\nchangeset/lib/rom/changeset/stateful.rb:219: [UnknownParam] @param tag has unknown parameter name: assoc\ncore/lib/rom/associations/definitions/abstract.rb:66: [UnknownParam] @param tag has unknown parameter name: options\ncore/lib/rom/attribute.rb:339: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/command_registry.rb:52: [UnknownParam] @param tag has unknown parameter name: name\ncore/lib/rom/commands/class_interface.rb:78: [UnknownParam] @param tag has unknown parameter name: command\ncore/lib/rom/commands/class_interface.rb:79: [UnknownParam] @param tag has unknown parameter name: parent\ncore/lib/rom/commands/class_interface.rb:108: [UnknownParam] @param tag has unknown parameter name: options. Did you mean `_options`?\ncore/lib/rom/commands/class_interface.rb:118: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/configuration.rb:46: [UnknownParam] @param tag has unknown parameter name: The\ncore/lib/rom/configuration.rb:47: [UnknownParam] @param tag has unknown parameter name: Plugin. Did you mean `plugin`?\ncore/lib/rom/gateway.rb:171: [UnknownParam] @param tag has unknown parameter name: Transaction\ncore/lib/rom/global.rb:40: [InvalidTagFormat] Invalid tag format for @example\ncore/lib/rom/global/plugin_dsl.rb:41: [UnknownParam] @param tag has unknown parameter name: adapter\ncore/lib/rom/memory/dataset.rb:54: [UnknownParam] @param tag has unknown parameter name: names\ncore/lib/rom/plugin_base.rb:38: [UnknownParam] @param tag has unknown parameter name: base. Did you mean `_base`?\ncore/lib/rom/plugin_registry.rb:140: [UnknownTag] Unknown tag @raises. Did you mean @raise?\ncore/lib/rom/plugin_registry.rb:187: [UnknownTag] Unknown tag @raises. Did you mean @raise?\ncore/lib/rom/relation.rb:297: [UnknownParam] @param tag has unknown parameter name: options\ncore/lib/rom/relation.rb:406: [UnknownParam] @param tag has unknown parameter name: new_options\ncore/lib/rom/relation.rb:524: [UnknownParam] @param tag has unknown parameter name: klass\ncore/lib/rom/relation/combined.rb:28: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/relation/curried.rb:69: [UnknownTag] Unknown tag @raises. Did you mean @raise?\ncore/lib/rom/relation/loaded.rb:91: [UnknownTag] Unknown tag @raises. Did you mean @raise?\ncore/lib/rom/schema.rb:144: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/schema.rb:300: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/schema.rb:311: [MissingParamName] @param tag has empty parameter name\ncore/lib/rom/types.rb:1: [UnknownNamespace] namespace Coercible is not recognized\ncore/lib/rom/types.rb:1: [UnknownNamespace] namespace Coercible is not recognized\ncore/lib/rom/types.rb:1: [UnknownNamespace] namespace Coercible is not recognized\nmapper/lib/rom/header.rb:47: [UnknownParam] @param tag has unknown parameter name: model\nmapper/lib/rom/processor/transproc.rb:212: [MissingParamName] @param tag has empty parameter name\n\n0 failures, 32 problems (2 seconds to run)\n```\n\u003c/details\u003e\n\nIt is basically the same as above, and:\n\n* sorted by files/lines instead of \"reported when found\" approach;\n* with short stats at the end;\n* returning proper exit code (0 if no problems/parsing errors, non-0 otherwise), which allows `yard-junk`\n  to be integrated into CI pipeline, and control that new PRs will not screw docs (forgetting to\n  rename parameters in docs when they are renamed in code, for example).\n\nAs a nice addition, `yard-junk` command uses its own links to code objects resolver, which is 10x\nfaster (and, eventually, more correct) than YARD's own approach to resolve links when rendering docs.\n\n## Usage\n\nIt is a `yard-junk` gem, install it as usual, or add to your `Gemfile`.\n\n### Better logs\n\nAdd this to your `.yardopts` file:\n```\n--plugin junk\n```\n\nAfter that, just run `yard` or `yard doc` as usual, and enjoy better logs! You can also setup JunkYard\nlogs by passing options (in the same `.yardopts`):\n```\n--junk-log-format FORMAT_STR\n--junk-log-ignore ERROR_TYPE1,ERROR_TYPE2,...\n```\n\nFormat is usual Ruby's [#format](https://ruby-doc.org/core-2.2.3/Kernel.html#method-i-format) method\nwith named fields:\n* `message` -- error message;\n* `file` -- error file;\n* `line` -- error line;\n* `type` -- error type.\n\nDefault format is `%{file}:%{line}: [%{type}] %{message}`, as shown above.\n\n`--junk-log-ignore` option allows to ingore error classes by their type names (shown in logs in `[]`).\nBy default, `Undocumentable` error is ignored: it is produced as metaprogramming pieces of code like\n```ruby\nattr_reader *OPTIONS\n```\nor\n```ruby\ninclude Rails.routes\n```\n...and typically have no way to fix, while polluting logs with a lot of, well, junk.\n\n### Standalone docs check\n\nJust run `yard-junk` command after gem is installed. Optionally, you can setup \"formatters\" to use:\n\n* text formatter: suitable for console, sparse colorized output;\n* HTML formatter: suitable as CI artifact, readable in browser.\n\nExamples:\n\n* `yard-junk` (default run, outputs text to STDOUT);\n* `yard-junk --text` (same as above);\n* `yard-junk --text logs/yard.log` (set the output path);\n* `yard-junk --text --html build-artifacts/junk-yard.html` (several formatters at once: text to console,\n  HTML to file).\n\nYou can also specify pathes to report (useful when working on large codebases, when you want to check\nonly your recent piece of work):\n\n```\nyard-junk --path some/path/\nyard-junk --path other/path/*sample*.rb\nyard-junk --path specific/path.rb\nyard-junk --path several,different/*.rb,patterns.rb\n```\n\nNote that `yard-junk` would parse the pathes that set in `.yardopts` as usually, and then\n**filter report** by pattern specified.\n\n### Rake task (integrating in CI)\n\nAdd this to your `Rakefile`:\n\n```ruby\nrequire 'yard-junk/rake'\nYardJunk::Rake.define_task\n```\n\nand then run it (or add to your `.travis.yml`) as\n```\nrake yard:junk\n```\n\nThe Rake task also takes formatter arguments, at task-definition time:\n\n```ruby\nYardJunk::Rake.define_task(:text) # default\nYardJunk::Rake.define_task(text: 'logs/yard.log') # text to file\nYardJunk::Rake.define_task(:text, html: 'build-artifacts/junk-yard.html') # text to STDOUT, html to file\n```\n\n## Reasons\n\nSmall problems in docs lead to a decrease in readability and usability. But it is hard to check for\nall those problems manually due to YARD's cumbersome output, and lack of CI-ready doc checking tools.\n\nThe idea of a regularly structured logger was initially [proposed](https://github.com/lsegal/yard/issues/1007)\nas an enhancement for YARD itself, and even some steps were made by YARD's author in that direction,\nbut the idea was abandoned since.\n\nTherefore, this independent tool was made.\n\n## Caveats\n\nSometimes YARD doesn't provide enough information to guess in which line of code the problem is;\nin those cases `yard-junk` just writes something like `file.rb:1` (to stay consistent and not break\ngo-to-file tools).\n\n## Roadmap\n\n* Docs for usage as a system-wide YARD plugin;\n* Docs for internals;\n* Documentation quality checks as a next level of YARD checker ([#14](https://github.com/zverok/yard-junk/issues/14)).\n\n## Some examples of problems found in popular gems:\n\n**NB: All of those are excellent libs! The showcase is of \"how hard it is to maintain docs quality\",\nnot of \"how ignorant other programmers are\".**\n\n\u003cdetails\u003e\u003csummary\u003ehttparty: 2\u003c/summary\u003e\n\n```\nlib/httparty/exceptions.rb:2: [UnknownTag] Unknown tag @abstact. Did you mean @abstract?\nlib/httparty/exceptions.rb:20: [MissingParamName] @param tag has empty parameter name\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003evcr: 7\u003c/summary\u003e\n\n```\nlib/vcr/deprecations.rb:71: [UnknownParam] @param tag has unknown parameter name: name\nlib/vcr/deprecations.rb:73: [UnknownParam] @param tag has unknown parameter name: options\nlib/vcr/linked_cassette.rb:12: [UnknownParam] @param tag has unknown parameter name: context-owned\nlib/vcr/linked_cassette.rb:13: [UnknownParam] @param tag has unknown parameter name: context-unowned\nlib/vcr/linked_cassette.rb:55: [UnknownParam] @param tag has unknown parameter name: context-owned\nlib/vcr/linked_cassette.rb:56: [UnknownParam] @param tag has unknown parameter name: context-unowned\nlib/vcr/test_frameworks/cucumber.rb:27: [UnknownParam] @param tag has unknown parameter name: options\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eeventmachine: 19\u003c/summary\u003e\n\n```\nlib/em/channel.rb:39: [UnknownParam] @param tag has unknown parameter name: Subscriber\nlib/em/connection.rb:603: [InvalidLink] Cannot resolve link to Socket.unpack_sockaddr_in from text: {Socket.unpack_sockaddr_in}\nlib/em/connection.rb:726: [InvalidLink] Cannot resolve link to EventMachine.notify_readable from text: {EventMachine.notify_readable}\nlib/em/connection.rb:726: [InvalidLink] Cannot resolve link to EventMachine.notify_writable from text: {EventMachine.notify_writable}\nlib/em/connection.rb:739: [InvalidLink] Cannot resolve link to EventMachine.notify_readable from text: {EventMachine.notify_readable}\nlib/em/connection.rb:739: [InvalidLink] Cannot resolve link to EventMachine.notify_writable from text: {EventMachine.notify_writable}\nlib/em/protocols/httpclient2.rb:263: [InvalidLink] Cannot resolve link to |response| from text: {|response| puts response.content }\nlib/em/protocols/httpclient2.rb:276: [InvalidLink] Cannot resolve link to |response| from text: {|response| puts response.content }\nlib/em/protocols/line_protocol.rb:9: [InvalidLink] Cannot resolve link to line from text: {line}\nlib/em/protocols/object_protocol.rb:9: [InvalidLink] Cannot resolve link to 'you from text: {'you said' =\u003e obj}\nlib/em/protocols/smtpclient.rb:138: [InvalidLink] Cannot resolve link to \"Subject\" from text: {\"Subject\" =\u003e \"Bogus\", \"CC\" =\u003e \"\u003ca href=\"mailto:myboss@example.com\"\u003emyboss@example.com\u003c/a\u003e\"}\nlib/em/protocols/smtpclient.rb:138: [InvalidLink] Cannot resolve link to :type=\u003e:plain, from text: {:type=\u003e:plain, :username=\u003e\"\u003ca href=\"mailto:mickey@disney.com\"\u003emickey@disney.com\u003c/a\u003e\", :password=\u003e\"mouse\"}\nlib/em/protocols/smtpserver.rb:435: [InvalidLink] Cannot resolve link to :cert_chain_file from text: {:cert_chain_file =\u003e \"/etc/ssl/cert.pem\", :private_key_file =\u003e \"/etc/ssl/private/cert.key\"}\nlib/em/protocols/socks4.rb:13: [InvalidLink] Cannot resolve link to data from text: {data}\nlib/em/spawnable.rb:47: [InvalidLink] Cannot resolve link to xxx from text: {xxx}\nlib/eventmachine.rb:215: [InvalidLink] Cannot resolve link to EventMachine.stop from text: {EventMachine.stop}\nlib/eventmachine.rb:231: [InvalidLink] Cannot resolve link to EventMachine::Callback from text: {EventMachine::Callback}\nlib/eventmachine.rb:319: [UnknownParam] @param tag has unknown parameter name: delay\nlib/eventmachine.rb:345: [UnknownParam] @param tag has unknown parameter name: delay\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eaddressable: 8\u003c/summary\u003e\n\n```\nlib/addressable/template.rb:197: [UnknownParam] @param tag has unknown parameter name: *indexes. Did you mean `indexes`?\nlib/addressable/uri.rb:296: [UnknownParam] @param tag has unknown parameter name: *uris. Did you mean `uris`?\nlib/addressable/uri.rb:1842: [UnknownParam] @param tag has unknown parameter name: The\nlib/addressable/uri.rb:1943: [UnknownParam] @param tag has unknown parameter name: The\nlib/addressable/uri.rb:1958: [UnknownParam] @param tag has unknown parameter name: The\nlib/addressable/uri.rb:2023: [UnknownParam] @param tag has unknown parameter name: The\nlib/addressable/uri.rb:2244: [UnknownParam] @param tag has unknown parameter name: *components. Did you mean `components`?\nlib/addressable/uri.rb:2275: [UnknownParam] @param tag has unknown parameter name: *components. Did you mean `components`?\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003ehashie: 16 (mostly not escaped code in docs)\u003c/summary\u003e\n\n```\nlib/hashie/extensions/coercion.rb:68: [UnknownParam] @param tag has unknown parameter name: key\nlib/hashie/extensions/coercion.rb:69: [UnknownParam] @param tag has unknown parameter name: into\nlib/hashie/extensions/deep_find.rb:7: [InvalidLink] Cannot resolve link to user: from text: {user: {location: {address: '123 Street'}\nlib/hashie/extensions/deep_find.rb:7: [InvalidLink] Cannot resolve link to user: from text: {user: {location: {address: '123 Street'}\nlib/hashie/extensions/deep_find.rb:16: [InvalidLink] Cannot resolve link to location: from text: {location: {address: '123 Street'}\nlib/hashie/extensions/deep_find.rb:16: [InvalidLink] Cannot resolve link to location: from text: {location: {address: '123 Street'}\nlib/hashie/extensions/deep_find.rb:27: [InvalidLink] Cannot resolve link to users: from text: {users: [{location: {address: '123 Street'}\nlib/hashie/extensions/deep_find.rb:27: [InvalidLink] Cannot resolve link to users: from text: {users: [{location: {address: '123 Street'}\nlib/hashie/extensions/deep_find.rb:36: [InvalidLink] Cannot resolve link to location: from text: {location: {address: '123 Street'}\nlib/hashie/extensions/deep_find.rb:36: [InvalidLink] Cannot resolve link to location: from text: {location: {address: '123 Street'}\nlib/hashie/extensions/deep_find.rb:36: [InvalidLink] Cannot resolve link to location: from text: {location: {address: '234 Street'}\nlib/hashie/extensions/deep_find.rb:36: [InvalidLink] Cannot resolve link to location: from text: {location: {address: '234 Street'}\nlib/hashie/extensions/deep_find.rb:36: [InvalidLink] Cannot resolve link to location: from text: {location: {address: '234 Street'}\nlib/hashie/extensions/deep_find.rb:36: [InvalidLink] Cannot resolve link to location: from text: {location: {address: '234 Street'}\nlib/hashie/mash.rb:32: [InvalidLink] Cannot resolve link to :a from text: {:a =\u003e {:b =\u003e 23, :d =\u003e {:e =\u003e \"abc\"}\nlib/hashie/mash.rb:32: [InvalidLink] Cannot resolve link to :g from text: {:g =\u003e 44, :h =\u003e 29}\n```\n\u003c/details\u003e\n\n## Authors\n\n* [Victor Shepelev](https://github.com/zverok)\n* [Olle Jonsson](https://github.com/olleolleolle)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzverok%2Fyard-junk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzverok%2Fyard-junk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzverok%2Fyard-junk/lists"}