yard 0.9.24 → 0.9.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53bb10d04117e8e6b53dc07a0b93520b0a08b713a77588254c85dfeec52ace67
-  data.tar.gz: 4945cd96795da8c07ef2eb571536ba0ad5f6a9a0f185717c6ba20943e5cc3153
+  metadata.gz: '069382132042276687f3551fe9f55d143635a028d5e4a1c5796e122a6871af8d'
+  data.tar.gz: f9b76a7d6051ce84375ba417a80f477961bfd2a03e9d8b9908615d7958bf96a0
 SHA512:
-  metadata.gz: 50ee44093b616fddc463b77168111c4c5047995a83582968792c9bab6ec4ace104ccd074397e4925c7fbe5e2c2c273413c9163a00ad016a3c4a895d433b0b1d4
-  data.tar.gz: 824c71f1724f55ccc7f4a0e98e69df583d0f553ae908ec75fe1d080b596e1bed028c12d6d422f3a9841a5b50e07394cd2059c4412a91c48efb23840977346f44
+  metadata.gz: a270998fd0d1efc6b41fa43c0b273935953c57cc17c95a11b7faa91476f2edeae14e481570acdaa3b3e824eaf9da9dd4bc3941b9e2cdbee76a193ac129251573
+  data.tar.gz: f196bef07edee0bdbca743d03db9e13f589ab9b19f5ebe7fefdee2b7fadf784b88d0c811cf8f67471fd58718247f780abaa67a7a16556729944e6f56ebc7abf0

data/.rubocop.yml

@@ -1,13 +1,11 @@
 #inherit_from:
 #  - .rubocop_todo.yml
 
-AllCops:
-  TargetRubyVersion: 2.4
-  Exclude:
-    - 'vendor/**/*' # need to reset this apparently
-    - 'lib/yard/parser/ruby/legacy/ruby_lex.rb' # old file, don't touch
 Metrics:
   Enabled: false
+Layout/LineLength:
+  AutoCorrect: true
+  Max: 100
 Style/Semicolon:
   AllowAsExpressionSeparator: true
 Style/Documentation:
@@ -16,23 +14,21 @@ Style/ClassVars:
   Enabled: false
 Style/HashSyntax:
   EnforcedStyle: hash_rockets
-Style/SpaceInsideHashLiteralBraces:
+Layout/SpaceInsideHashLiteralBraces:
   EnforcedStyle: no_space
-Style/SpaceInsideBlockBraces:
+Layout/SpaceInsideBlockBraces:
   SpaceBeforeBlockParameters: false
-Style/MultilineMethodCallIndentation:
-  EnforcedStyle: indented
 Style/NumericPredicate: # ruby 1.8/1.9 do not have positive?/negative?
   EnforcedStyle: comparison
-Style/MultilineMethodCallIndentation:
+Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
-Style/DotPosition:
+Layout/DotPosition:
   EnforcedStyle: trailing
 Style/FormatString:
   EnforcedStyle: percent
-Style/IndentArray:
+Layout/FirstArrayElementIndentation:
   EnforcedStyle: consistent
-Style/IndentHash:
+Layout/FirstHashElementIndentation:
   EnforcedStyle: consistent
 
 # Disable these until we know what to do with them
@@ -40,29 +36,31 @@ Style/SafeNavigation:
   Enabled: false # not supported in 1.8...2.1
 Style/GuardClause: # does not provide much value
   Enabled: false
-Style/VariableNumber:
+Naming/VariableNumber:
+  Enabled: false
+Naming/AccessorMethodName: # this creates breaking changes in the API
   Enabled: false
-Style/AccessorMethodName: # this creates breaking changes in the API
+Naming/PredicateName: # this creates breaking changes in the API
   Enabled: false
-Style/PredicateName: # this creates breaking changes in the API
+Style/MethodMissingSuper: # this doesn't exist in 1.8/1.9
   Enabled: false
-Style/MethodMissing: # this doesn't exist in 1.8/1.9
+Style/MissingRespondToMissing: # this doesn't exist in 1.8/1.9
   Enabled: false
 Style/Lambda: # not supported in 1.8
   Enabled: false
 Style/EachWithObject: # not supported in 1.8
   Enabled: false
-Style/AlignParameters: # does not work correctly with subsequent block
+Layout/ParameterAlignment: # does not work correctly with subsequent block
   Enabled: false
-Style/AlignArray: # does not support indentation
+Layout/ArrayAlignment: # does not support indentation
   Enabled: false
-Style/AlignHash: # does not support indentation
+Layout/HashAlignment: # does not support indentation
   Enabled: false
 Style/MultilineTernaryOperator:
   Enabled: false
 Style/ClassAndModuleChildren:
   Enabled: false
-Style/EmptyLineBetweenDefs:
+Layout/EmptyLineBetweenDefs:
   AllowAdjacentOneLineDefs: true
 Style/SingleLineMethods:
   Enabled: false
@@ -91,9 +89,24 @@ Style/GlobalVars:
   Exclude:
     - benchmarks/**/*.rb
     - spec/**/*.rb
-Lint/UnneededSplatExpansion:
+Lint/RedundantSplatExpansion:
   Enabled: false
-Lint/Eval:
+Security/Eval:
   Exclude:
     - benchmarks/**/*.rb
-- spec/**/*.rb
+    - spec/**/*.rb
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: false
+Lint/RaiseException:
+  Enabled: false
+Lint/StructNewOverride:
+  Enabled: false
+Style/ExponentialNotation:
+  Enabled: false
+Style/HashEachMethods:
+  Enabled: false
+Style/HashTransformKeys:
+  Enabled: false
+Style/HashTransformValues:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # master
 
+# 0.9.25 - May 3rd, 2020
+
+[0.9.25]: https://github.com/lsegal/yard/compare/v0.9.24...v0.9.25
+
+- Fix parsing issue with conditional blocks mixed with conditional modifiers.
+  (#1308, #1324, #1326, #1327)
+- Add table of contents IDs to redcarpet generated markdown. (#1323)
+- Backport fixes for Ruby 1.9 (#1320)
+- Fix parsing of checksums in yard server (#1301)
+- Map Ruby C variable error names to Ruby classes (#1270, #1275)
+- Fix initialization of RDocMarkup across threads (#1318)
+- Remove warning for Kernel#open (#1312)
+- Omit spec files in gem package (#1307)
+- README updates (#1322)
+
 # 0.9.24 - January 8th, 2020
 
 [0.9.24]: https://github.com/lsegal/yard/compare/v0.9.23...v0.9.24
@@ -43,9 +58,9 @@
 
 - Fix parsing of stringified Symbols in Ruby source (#1256).
 - Fix path traversal vulnerability in `yard server`. This bug would allow
- unsanitized HTTP requests to access arbitrary files on the machine of a
- `yard server` host under certain conditions. Thanks to CuongMX from
- Viettel Cyber Security for discovering this vulnerability.
+  unsanitized HTTP requests to access arbitrary files on the machine of a
+  `yard server` host under certain conditions. Thanks to CuongMX from
+  Viettel Cyber Security for discovering this vulnerability.
 
 # 0.9.19 - April 2nd, 2019
 

data/README.md

@@ -1,23 +1,22 @@
 # YARD: Yay! A Ruby Documentation Tool
 
-[![Homepage](http://img.shields.io/badge/home-yardoc.org-blue.svg)](http://yardoc.org)
-[![GitHub](http://img.shields.io/badge/github-lsegal/yard-blue.svg)](http://github.com/lsegal/yard)
-[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/yard/frames)
+[![Homepage](https://img.shields.io/badge/home-yardoc.org-blue.svg)](http://yardoc.org)
+[![GitHub](https://img.shields.io/badge/github-lsegal/yard-blue.svg)](http://github.com/lsegal/yard)
+[![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/yard/frames)
 
 [![Gem Version](https://badge.fury.io/rb/yard.svg)](http://github.com/lsegal/yard/releases)
 [![Build Status](https://travis-ci.org/lsegal/yard.svg?branch=master)](https://travis-ci.org/lsegal/yard)
 [![Coverage Status](https://coveralls.io/repos/github/lsegal/yard/badge.svg)](https://coveralls.io/github/lsegal/yard)
-[![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
+[![License](https://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
 
 ## Synopsis
 
-YARD is a documentation generation tool for the Ruby programming language.
-It enables the user to generate consistent, usable documentation that can be
+YARD is a documentation generation tool for the Ruby programming language. It
+enables the user to generate consistent, usable documentation that can be
 exported to a number of formats very easily, and also supports extending for
 custom Ruby constructs such as custom class level definitions. Below is a
 summary of some of YARD's notable features.
 
-
 ## Feature List
 
 **1. RDoc/SimpleMarkup Formatting Compatibility**: YARD is made to be compatible
@@ -25,22 +24,23 @@ with RDoc formatting. In fact, YARD does no processing on RDoc documentation
 strings, and leaves this up to the output generation tool to decide how to
 render the documentation.
 
-**2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other languages**:
-YARD uses a '@tag' style definition syntax for meta tags alongside  regular code
-documentation. These tags should be able to happily sit side by side RDoc formatted
-documentation, but provide a much more consistent and usable way to describe
-important information about objects, such as what parameters they take and what types
-they are expected to be, what type a method should return, what exceptions it can
-raise, if it is deprecated, etc.. It also allows information to be better (and more
-consistently) organized during the output generation phase. You can find a list
-of tags in the {file:docs/Tags.md#taglist Tags.md} file.
-
-YARD also supports an optional "types" declarations for certain tags.
-This allows the developer to document type signatures for ruby methods and
-parameters in a non intrusive but helpful and consistent manner. Instead of
-describing this data in the body of the description, a developer may formally
-declare the parameter or return type(s) in a single line. Consider the
-following method documented with YARD formatting:
+**2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other
+languages**: YARD uses a '@tag' style definition syntax for meta tags alongside
+regular code documentation. These tags should be able to happily sit side by
+side RDoc formatted documentation, but provide a much more consistent and usable
+way to describe important information about objects, such as what parameters
+they take and what types they are expected to be, what type a method should
+return, what exceptions it can raise, if it is deprecated, etc.. It also allows
+information to be better (and more consistently) organized during the output
+generation phase. You can find a list of tags in the {file:docs/Tags.md#taglist
+Tags.md} file.
+
+YARD also supports an optional "types" declarations for certain tags. This
+allows the developer to document type signatures for ruby methods and parameters
+in a non intrusive but helpful and consistent manner. Instead of describing this
+data in the body of the description, a developer may formally declare the
+parameter or return type(s) in a single line. Consider the following method
+documented with YARD formatting:
 
 ```ruby
 # Reverses the contents of a String or IO object.
@@ -53,13 +53,12 @@ def reverse(contents)
 end
 ```
 
-With the above @param tag, we learn that the contents parameter can either be
-a String or any object that responds to the 'read' method, which is more
-powerful than the textual description, which says it should be an IO object.
-This also informs the developer that they should expect to receive a String
-object returned by the method, and although this may be obvious for a
-'reverse' method, it becomes very useful when the method name may not be as
-descriptive.
+With the above @param tag, we learn that the contents parameter can either be a
+String or any object that responds to the 'read' method, which is more powerful
+than the textual description, which says it should be an IO object. This also
+informs the developer that they should expect to receive a String object
+returned by the method, and although this may be obvious for a 'reverse' method,
+it becomes very useful when the method name may not be as descriptive.
 
 **3. Custom Constructs and Extensibility of YARD**: YARD is designed to be
 extended and customized by plugins. Take for instance the scenario where you
@@ -73,12 +72,12 @@ end
 ```
 
 This custom declaration provides dynamically generated code that is hard for a
-documentation tool to properly document without help from the developer. To
-ease the pains of manually documenting the procedure, YARD can be extended by
-the developer to handle the `cattr_accessor` construct and automatically create
-an attribute on the class with the associated documentation. This makes
-documenting external API's, especially dynamic ones, a lot more consistent for
-consumption by the users.
+documentation tool to properly document without help from the developer. To ease
+the pains of manually documenting the procedure, YARD can be extended by the
+developer to handle the `cattr_accessor` construct and automatically create an
+attribute on the class with the associated documentation. This makes documenting
+external API's, especially dynamic ones, a lot more consistent for consumption
+by the users.
 
 YARD is also designed for extensibility everywhere else, allowing you to add
 support for new programming languages, new data structures and even where/how
@@ -88,21 +87,20 @@ data is stored.
 dumped Namespace) which can be reloaded to do generation at a later date, or
 even auditing on code. This means that any developer can use the raw data to
 perform output generation for any custom format, such as YAML, for instance.
-While YARD plans to support XHTML style documentation output as well as
-command line (text based) and possibly XML, this may still be useful for those
-who would like to reap the benefits of YARD's processing in other forms, such
-as throwing all the documentation into a database. Another useful way of
-exploiting this raw data format would be to write tools that can auto generate
-test cases, for example, or show possible unhandled exceptions in code.
-
-**5. Local Documentation Server**: YARD can serve documentation for projects
-or installed gems (similar to `gem server`) with the added benefit of dynamic
+While YARD plans to support XHTML style documentation output as well as command
+line (text based) and possibly XML, this may still be useful for those who would
+like to reap the benefits of YARD's processing in other forms, such as throwing
+all the documentation into a database. Another useful way of exploiting this raw
+data format would be to write tools that can auto generate test cases, for
+example, or show possible unhandled exceptions in code.
+
+**5. Local Documentation Server**: YARD can serve documentation for projects or
+installed gems (similar to `gem server`) with the added benefit of dynamic
 searching, as well as live reloading. Using the live reload feature, you can
 document your code and immediately preview the results by refreshing the page;
 YARD will do all the work in re-generating the HTML. This makes writing
 documentation a much faster process.
 
-
 ## Installing
 
 To install YARD, use the following command:
@@ -117,14 +115,13 @@ Alternatively, if you've checked the source out directly, you can call
 `rake install` from the root project directory.
 
 **Important Note for Debian/Ubuntu users:** there's a possible chance your Ruby
-install lacks RDoc, which is occasionally used by YARD to convert markup to HTML.
-If running `which rdoc` turns up empty, install RDoc by issuing:
+install lacks RDoc, which is occasionally used by YARD to convert markup to
+HTML. If running `which rdoc` turns up empty, install RDoc by issuing:
 
 ```sh
 $ sudo apt-get install rdoc
 ```
 
-
 ## Usage
 
 There are a couple of ways to use YARD. The first is via command-line, and the
@@ -133,8 +130,8 @@ second is the Rake task.
 **1. yard Command-line Tool**
 
 YARD comes packaged with a executable named `yard` which can control the many
-functions of YARD, including generating documentation, graphs running the
-YARD server, and so on. To view a list of available YARD commands, type:
+functions of YARD, including generating documentation, graphs running the YARD
+server, and so on. To view a list of available YARD commands, type:
 
 ```sh
 $ yard --help
@@ -148,39 +145,36 @@ functionality.
 <span class="note">The `yardoc` executable is a shortcut for `yard doc`.</span>
 
 The most common command you will probably use is `yard doc`, or `yardoc`. You
-can type `yardoc --help` to see the options that YARD provides, but the
-easiest way to generate docs for your code is to simply type `yardoc` in your
-project root. This will assume your files are
-located in the `lib/` directory. If they are located elsewhere, you can specify
-paths and globs from the commandline via:
+can type `yardoc --help` to see the options that YARD provides, but the easiest
+way to generate docs for your code is to simply type `yardoc` in your project
+root. This will assume your files are located in the `lib/` directory. If they
+are located elsewhere, you can specify paths and globs from the commandline via:
 
 ```sh
 $ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
 ```
 
-The tool will generate a `.yardoc` file which will store the cached database
-of your source code and documentation. If you want to re-generate your docs
-with another template you can simply use the `--use-cache` (or -c)
-option to speed up the generation process by skipping source parsing.
+The tool will generate a `.yardoc` file which will store the cached database of
+your source code and documentation. If you want to re-generate your docs with
+another template you can simply use the `--use-cache` (or -c) option to speed up
+the generation process by skipping source parsing.
 
 YARD will by default only document code in your public visibility. You can
-document your protected and private code by adding `--protected` or
-`--private` to the option switches. In addition, you can add `--no-private`
-to also ignore any object that has the `@private` meta-tag. This is similar
-to RDoc's ":nodoc:" behaviour, though the distinction is important. RDoc
-implies that the object with :nodoc: would not be documented, whereas
-YARD still recommends documenting private objects for the private API (for
-maintainer/developer consumption).
+document your protected and private code by adding `--protected` or `--private`
+to the option switches. In addition, you can add `--no-private` to also ignore
+any object that has the `@private` meta-tag. This is similar to RDoc's ":nodoc:"
+behaviour, though the distinction is important. RDoc implies that the object
+with :nodoc: would not be documented, whereas YARD still recommends documenting
+private objects for the private API (for maintainer/developer consumption).
 
-You can also add extra informative files (README, LICENSE) by separating
-the globs and the filenames with '-'.
+You can also add extra informative files (README, LICENSE) by separating the
+globs and the filenames with '-'.
 
 ```sh
 $ yardoc 'app/**/*.rb' - README LICENSE FAQ
 ```
 
-If no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is
-used:
+If no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is used:
 
 ```sh
 $ yardoc - README LICENSE FAQ
@@ -188,18 +182,18 @@ $ yardoc - README LICENSE FAQ
 
 Note that the README file can be specified with its own `--readme` switch.
 
-You can also add a `.yardopts` file to your project directory which lists
-the switches separated by whitespace (newlines or space) to pass to yardoc
-whenever it is run. A full overview of the `.yardopts` file can be found in
+You can also add a `.yardopts` file to your project directory which lists the
+switches separated by whitespace (newlines or space) to pass to yardoc whenever
+it is run. A full overview of the `.yardopts` file can be found in
 {YARD::CLI::Yardoc}.
 
 ### Queries
 
 The `yardoc` tool also supports a `--query` argument to only include objects
-that match a certain data or meta-data query. The query syntax is Ruby, though
-a few shortcuts are available. For instance, to document only objects that have
-an "@api" tag with the value "public", all of the following syntaxes would give
-the same result:
+that match a certain data or meta-data query. The query syntax is Ruby, though a
+few shortcuts are available. For instance, to document only objects that have an
+"@api" tag with the value "public", all of the following syntaxes would give the
+same result:
 
 ```sh
 --query '@api.text == "public"'
@@ -207,8 +201,8 @@ the same result:
 --query 'has_tag?(:api) && tag(:api).text == "public"'
 ```
 
-Note that the "@tag" syntax returns the first tag named "tag" on the object.
-To return the array of all tags named "tag", use "@@tag".
+Note that the "@tag" syntax returns the first tag named "tag" on the object. To
+return the array of all tags named "tag", use "@@tag".
 
 Multiple `--query` arguments are allowed in the command line parameters. The
 following two lines both check for the existence of a return and param tag:
@@ -235,12 +229,12 @@ YARD::Rake::YardocTask.new do |t|
 end
 ```
 
-All the settings: `files`, `options` and `stats_options` are optional. `files` will default to
-`lib/**/*.rb`, `options` will represents any options you might want
-to add and `stats_options` will pass extra options to the stats command.
-Again, a full list of options is available by typing `yardoc --help`
-in a shell. You can also override the options at the Rake command-line with the
-OPTS environment variable:
+All the settings: `files`, `options` and `stats_options` are optional. `files`
+will default to `lib/**/*.rb`, `options` will represents any options you might
+want to add and `stats_options` will pass extra options to the stats command.
+Again, a full list of options is available by typing `yardoc --help` in a shell.
+You can also override the options at the Rake command-line with the OPTS
+environment variable:
 
 ```sh
 $ rake yard OPTS='--any --extra --opts'
@@ -272,15 +266,17 @@ directory. `yri` will also cache lookups there.
 
 **4. `yard server` Documentation Server**
 
-The `yard server` command serves documentation for a local project or all installed
-RubyGems. To serve documentation for a project you are working on, simply run:
+The `yard server` command serves documentation for a local project or all
+installed RubyGems. To serve documentation for a project you are working on,
+simply run:
 
 ```sh
 $ yard server
 ```
 
 And the project inside the current directory will be parsed (if the source has
-not yet been scanned by YARD) and served at [http://localhost:8808](http://localhost:8808).
+not yet been scanned by YARD) and served at
+[http://localhost:8808](http://localhost:8808).
 
 ### Live Reloading
 
@@ -297,10 +293,9 @@ To serve documentation for all installed gems, call:
 $ yard server --gems
 ```
 
-This will also automatically build documentation for any gems that have not
-been previously scanned. Note that in this case there will be a slight delay
-between the first request of a newly parsed gem.
-
+This will also automatically build documentation for any gems that have not been
+previously scanned. Note that in this case there will be a slight delay between
+the first request of a newly parsed gem.
 
 **5. `yard graph` Graphviz Generator**
 
@@ -309,22 +304,22 @@ requires [Graphviz](http://www.graphviz.org) and the `dot` binary. By default
 this will generate a graph of the classes and modules in the best UML2 notation
 that Graphviz can support, but without any methods listed. With the `--full`
 option, methods and attributes will be listed. There is also a `--dependencies`
-option to show mixin inclusions. You can output to stdout or a file, or pipe directly
-to `dot`. The same public, protected and private visibility rules apply to `yard graph`.
-More options can be seen by typing `yard graph --help`, but here is an example:
+option to show mixin inclusions. You can output to stdout or a file, or pipe
+directly to `dot`. The same public, protected and private visibility rules apply
+to `yard graph`. More options can be seen by typing `yard graph --help`, but
+here is an example:
 
 ```sh
 $ yard graph --protected --full --dependencies
 ```
 
-
 ## Changelog
 
 See {file:CHANGELOG.md} for a list of changes.
 
 ## License
 
-YARD &copy; 2007-2018 by [Loren Segal](mailto:lsegal@soen.ca). YARD is
-licensed under the MIT license except for some files which come from the
-RDoc/Ruby distributions. Please see the {file:LICENSE} and {file:LEGAL}
-documents for more information.
+YARD &copy; 2007-2020 by [Loren Segal](mailto:lsegal@soen.ca). YARD is licensed
+under the MIT license except for some files which come from the RDoc/Ruby
+distributions. Please see the {file:LICENSE} and {file:LEGAL} documents for more
+information.