Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Layout/LineLength AllowURI does not allow long URLs in yardoc comments to have titles #10374

Closed
dmolesUC opened this issue Jan 24, 2022 · 0 comments · Fixed by #10459
Closed
Labels

Comments

@dmolesUC
Copy link
Contributor

dmolesUC commented Jan 24, 2022

Expected behavior

YARD comments with linked URLs of the form {<url> <title>} should not be offenses against Layout/LineLength when AllowURI is true.

Actual behavior

URLs of the form {<url>} are allowed, but including a space-separated <title> causes the check to fail.

Breaking the line, as:

{<url>
<title}

allows the test to pass, but breaks doc generation.

Steps to reproduce the problem

Create a Ruby file mms_id.rb containing the following code:

# frozen_string_literal: true

# {RecordId} subclass representing an Alma MMS ID. Note that only
# bibliographic records (prefix `99`) are supported.
#
# See {https://knowledge.exlibrisgroup.com/Alma/Product_Documentation/010Alma_Online_Help_(English)/Metadata_Management/005Introduction_to_Metadata_Management/020Record_Numbers Record Numbers}
# in the Alma documentation.
class MMSID; end

Run RuboCop with default configuration:

$ rubocop --debug mms_id.rb
For /private/tmp: Default configuration from /Users/david/.rvm/gems/ruby-3.0.2/gems/rubocop-1.25.0/config/default.yml
Use parallel by default.
Running parallel inspection
Inspecting 1 file
Scanning /private/tmp/mms_id.rb
Loading cache from /Users/david/.cache/rubocop_cache/7ccfad009a5b251caa148252ae8bbc361b628b36/6d7a3b621ca1730e04accd938619e4bdab66cfb1/7cd4b602c9667aa65e1b35069c3ea22b4b5228fa
C

Offenses:

mms_id.rb:6:177: C: Layout/LineLength: Line is too long. [192/120]
# See {https://knowledge.exlibrisgroup.com/Alma/Product_Documentation/010Alma_Online_Help_(English)/Metadata_Management/005Introduction_to_Metadata_Management/020Record_Numbers Record Numbers}
                                                                                                                                                                                ^^^^^^^^^^^^^^^^

1 file inspected, 1 offense detected
Finished in 0.11044700001366436 seconds

RuboCop version

1.25.0 (using Parser 3.1.0.0, rubocop-ast 1.15.1, running on ruby 3.0.2 arm64-darwin21)

Workarounds

Use Markdown syntax in YARD

When passing -m markdown as an argument to yard (or in .yardopts), it's possible to write URLs in the form [<title>](<url>). This passes Layout/LineLength, so long as the start of the URL is within the length limit, and so long as the (parenthesized) URL is the last text on the line.

Using rubocop:disable, awkwardly

It's possible to wrap documentation comments in rubocop:disable / rubocop:enable without YARD picking them up and including them in the generated docs, but it's awkward:

# rubocop:disable Layout/LineLength

# Class documentation goes here, after newline,
# but if we don't want the `enable` comment to be
# included in the docs, we have to move it past
# the first line of the code we're documenting
# 
# See {http://some-really-really-really-long-url.example.org/really-really-really-really-really/long/long/long/thing/with/a title}
class Foo
  # rubocop:enable Layout/LineLength

  # ...
end

Discussion

I think I understand the intent behind the find_excessive_uri_range and allowed_uri_position? calculations in Rubocop::Cop::LineLengthHelp, but I wonder if it's not trying to be too clever. I suspect a cop that simply ignored the first URL in a line of code when calculating the line length would be simpler and would still catch the vast majority of cases.

@dmolesUC dmolesUC changed the title Layout/LineLength AllowURI does not allow long URLs in yardoc titles to have comments Layout/LineLength AllowURI does not allow long URLs in yardoc comments to have titles Jan 24, 2022
@bbatsov bbatsov added the bug label Jan 28, 2022
ydah added a commit to ydah/rubocop that referenced this issue Mar 18, 2022
… long URIs in yardoc comments to have titles
ydah added a commit to ydah/rubocop that referenced this issue Mar 18, 2022
… long URIs in yardoc comments to have titles
bbatsov pushed a commit that referenced this issue Mar 22, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
2 participants