Project

General

Profile

Misc #13814

URI::FTP documentation for RDoc is broken

Added by aycabta (aycabta .) over 1 year ago. Updated over 1 year ago.

Status:
Closed
Priority:
Normal
Assignee:
-
[ruby-core:82379]

Description

This is related to #13813.

In lib/uri/ftp.rb, documentation for #path below:

    # Returns the path from an FTP URI.
    #
    # RFC 1738 specifically states that the path for an FTP URI does not
    # include the / which separates the URI path from the URI host. Example:
    #
    #     ftp://ftp.example.com/pub/ruby
    #
    # The above URI indicates that the client should connect to
    # ftp.example.com then cd pub/ruby from the initial login directory.
    #
    # If you want to cd to an absolute directory, you must include an
    # escaped / (%2F) in the path. Example:
    #
    #     ftp://ftp.example.com/%2Fpub/ruby
    #
    # This method will then return "/pub/ruby"
    #

The URIs what are started with "ftp://" is indented,
and indented documentation is treated as Ruby code.
So this becomes strange documentation, it's highlighted as some Ruby tokens.

The screenshot below is rendered HTML of URI::FTP documentation on ruby-doc.org:
http://ruby-doc.org/stdlib-2.4.1/libdoc/uri/rdoc/URI/FTP.html

URI of FTP as Ruby code

The second URI of FTP isn't highlighted,
because when a string is invalid as Ruby tokens in RDoc lexical analyser,
it's treated as plain text.
https://bugs.ruby-lang.org/projects/ruby-trunk/repository/revisions/59592/entry/lib/rdoc/markup/to_html.rb#L207

I think this should be fixed to correct documentation.
The patch what I attached on this issue fixes it like below:

    # Returns the path from an FTP URI.
    #
    # RFC 1738 specifically states that the path for an FTP URI does not
    # include the / which separates the URI path from the URI host. Example:
    #
    # +ftp://ftp.example.com/pub/ruby+
    #
    # The above URI indicates that the client should connect to
    # ftp.example.com then cd pub/ruby from the initial login directory.
    #
    # If you want to cd to an absolute directory, you must include an
    # escaped / (%2F) in the path. Example:
    #
    # +ftp://ftp.example.com/%2Fpub/ruby+
    #
    # This method will then return "/pub/ruby"
    #

Files

ftp-uri-documentation.patch (860 Bytes) ftp-uri-documentation.patch aycabta (aycabta .), 08/14/2017 05:33 PM

Associated revisions

Revision 16565fa2
Added by nobu (Nobuyoshi Nakada) over 1 year ago

ftp.rb: fix example format [ci skip]

  • lib/uri/ftp.rb: [DOC] fix format of example URLs. patched by aycabta (Code Ahss) at [ruby-core:82379]. [Bug #13814]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@59598 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

Revision 59598
Added by nobu (Nobuyoshi Nakada) over 1 year ago

ftp.rb: fix example format [ci skip]

  • lib/uri/ftp.rb: [DOC] fix format of example URLs. patched by aycabta (Code Ahss) at [ruby-core:82379]. [Bug #13814]

Revision 59598
Added by nobu (Nobuyoshi Nakada) over 1 year ago

ftp.rb: fix example format [ci skip]

  • lib/uri/ftp.rb: [DOC] fix format of example URLs. patched by aycabta (Code Ahss) at [ruby-core:82379]. [Bug #13814]

Revision 59598
Added by nobu (Nobuyoshi Nakada) over 1 year ago

ftp.rb: fix example format [ci skip]

  • lib/uri/ftp.rb: [DOC] fix format of example URLs. patched by aycabta (Code Ahss) at [ruby-core:82379]. [Bug #13814]

History

#1

Updated by nobu (Nobuyoshi Nakada) over 1 year ago

  • Status changed from Open to Closed

Applied in changeset trunk|r59598.


ftp.rb: fix example format [ci skip]

  • lib/uri/ftp.rb: [DOC] fix format of example URLs. patched by aycabta (Code Ahss) at [ruby-core:82379]. [Bug #13814]

Also available in: Atom PDF