Adding links to literals and Kernel #5192

BurdetteLamar · 2021-11-29T20:30:11Z

Adds links to the literals doc for classes that have literals. Also adds links to Kernel constructors for classes that have them (e.g., Array, Hash).

I have not yet treated the percent literals, b/c I'm undecided about where in the literals doc they belong: Does %w belong in Percent Literals (as now) or in Array Literals (b/c it creates an array)?

esparta · 2021-11-29T20:56:28Z

array.c

+ *  You can create an \Array object explicitly with:
+ *
+ *  - Global method {Array}[Kernel.html#method-i-Array].
+ *  - A {array literal}[doc/syntax/literals_rdoc.html#label-Array+Literals].


Suggested change

* - A {array literal}[doc/syntax/literals_rdoc.html#label-Array+Literals].

* - An {array literal}[doc/syntax/literals_rdoc.html#label-Array+Literals].

jeremyevans

Thanks for working on this. Many of these changes are OK, but I think there should be substantial changes, please see inline comments.

jeremyevans · 2021-11-29T20:44:29Z

doc/syntax/literals.rdoc

-If you are writing a large block of text you may use a "here document" or
-"heredoc":
+If you are writing a large block of text you may use a HereDocument,
+sometines written as HereDoc:


This part should be reverted. I've not seen anyone refer to heredocs using such capitalization.

jeremyevans · 2021-11-29T20:46:17Z

string.c

+ *
+ *  - Global method {String}[Kernel.html#method-i-String].
+ *  - A {string literal}[doc/syntax/literals_rdoc.html#label-String+Literals].
+ *  - A {HereDoc literal}[doc/syntax/literals_rdoc.html#label-Here+Document+Literals].


HereDoc -> heredoc

jeremyevans · 2021-11-29T20:50:52Z

array.c

+ *  You can create an \Array object explicitly with:
+ *
+ *  - Global method {Array}[Kernel.html#method-i-Array].
+ *  - A {array literal}[doc/syntax/literals_rdoc.html#label-Array+Literals].


The global methods are used for typecasting existing data to the expected type, they are not used for creating new instances (they accept an argument). If you mention the global methods at all, it should be under the section that discusses Many Ruby methods return #{type} objects. Also, please refer to them as Kernel methods, not global methods, since they aren't truly global (cannot use them in a BasicObject).

For the objects being discussed where you can use #{class}.new (e.g. Array#new), it should be listed directly after the literal form, since that is the next most common way of creating a new instance.

FWIW, I prefer the previous documentation even after fixing these issues. I don't think mentioning the to_a/to_ary methods (or similar methods for other classes) is important.

FWIW, I prefer the previous documentation even after fixing these issues.

Do you mean this to cover this entire PR?

No, only the parts of the PR where you are adding documentation about global methods and to_a/to_ary and similar methods.

Done (I think).

array.c

esparta · 2021-11-29T21:11:18Z

hash.c

+ *  - Instance method +to_i+, available in some Core and Standard Library classes.
+ *  - Instance method +to_int+, available in fewer classes.


Suggested change

* - Instance method +to_i+, available in some Core and Standard Library classes.

* - Instance method +to_int+, available in fewer classes.

* - Instance method +to_h+, available in some Core and Standard Library classes.

* - Instance method +to_hash+, available in fewer classes.

Done, and thanks @esparta. These are horrible errors.

nobu · 2021-11-29T22:30:56Z

array.c

- *  <code>[]</code>.  Arrays can contain different types of objects.  For
+ *  You can create an \Array object explicitly with:
+ *
+ *  - An {array literal}[doc/syntax/literals_rdoc.html#label-Array+Literals].


RDoc is not only for HTML format, should be rdoc-links.

This style is used in a lot of recent documentation, because people aren't sure how to use an rdoc-link to hyperlink to a specific heading in the generated documentation. Can you show an example of using an rdoc-link to generate the same link? Maybe it is possible with rdoc-label?

Basically, this comes down to these two usages:

* You can create an \Array object explicitly with: * * - An {array literal}[doc/syntax/literals_rdoc.html#label-Array+Literals]. * * You can convert certain objects to Arrays with: * * - \Method {Array}[Kernel.html#method-i-Array]. *

I have not found any form for these links that works, other than the above. If someone knows how to write these links without .html, please provide examples.

Specifically, what's needed is:

Link to an instance method in Kernel.

Link to a section in doc/syntax/literals.rdoc.

A link to an instance method Kernel would be Kernel#method_name. So those should be changed. In the example above, switch to:

* - \Method Kernel#Array

Similar changes for other method links.

Linking to section headings can be done with @, according to the rdoc documentation:

A heading inside the documentation can be linked by following the class or method by an @ then the heading name. RDoc::Markup@Links will link to this section like this: Links at RDoc::Markup. Spaces in headings with multiple words must be escaped with + like RDoc::Markup@Escaping+Text+Markup. Punctuation and other special characters must be escaped like CGI.escape.

That shows how to link to the section heading of a class. However, I'm not sure how to generate a link to a section heading of a file. Maybe {array literal}[doc/syntax/literals.rdoc@Array+Literals] works?

I've tried many things, including these:

{Array}[Kernel#Array] did not work; generated <a href="Kernel#Array">Array</a>. which did not work.

{array literal}[doc/syntax/literals.rdoc@Array+Literals]; generated <a href="doc/syntax/literals.rdoc@Array+Literals">array literal</a>, which also did not work.

Also, various forms with #method-i-Array did not work.

Could it be that things are different for a module such as Kernel? And for a file such as literals.rdoc?

No, Kernel#Array does not work. Maybe we need to hear from @nobu on this.

I'm asking @aycabta to fix RDoc.
The links are OK for now.

Thanks, @nobu. When RDoc is fixed, I will sweep the major classes free of these.

Link to a section in doc/syntax/literals.rdoc.

I think it would be better to use foo.rdoc#label-bar for labeled links to foo.rdoc instead of foo_rdoc.html#label-bar.

The label- part is a result of RDoc's internal processing, so it's probably not a good idea either, but if RDoc changes foo.rdoc#bar to foo_rdoc.html#label-bar, the part originally written as abc.rdoc#label-def will now be abc_rdoc.html#label-label-def. There are many places like this in the existing documentation. Even if other new notations are introduced, careful consideration is needed to ensure appropriate specifications.

Link to an instance method in Kernel.

I fixed it by ruby/rdoc#853. You can use Kernel#String.

Thanks, @aycabta. If I change to Kernel#String, I won't be able to verify in Ruby 3.0.2. If I put the 8 changes in a PR, can you verify?

jeremyevans

I'm OK with this, but let's see what @nobu has to say regarding the linking format before merging.

BurdetteLamar · 2021-12-01T13:08:33Z

@nobu, no one has offered any further improvements to these links. Can this be merged?

Adding links to literals and Kernel

62d6a63

BurdetteLamar added the Documentation Improvements to documentation. label Nov 29, 2021

BurdetteLamar requested a review from jeremyevans November 29, 2021 20:30

esparta reviewed Nov 29, 2021

View reviewed changes

jeremyevans requested changes Nov 29, 2021

View reviewed changes

esparta reviewed Nov 29, 2021

View reviewed changes

BurdetteLamar added 2 commits November 29, 2021 16:00

Adding links to literals and Kernel

a27edf0

Adding links to literals and Kernel

4edc1c5

BurdetteLamar requested review from jeremyevans and removed request for jeremyevans November 29, 2021 22:04

nobu reviewed Nov 29, 2021

View reviewed changes

jeremyevans approved these changes Nov 29, 2021

View reviewed changes

BurdetteLamar requested a review from nobu November 30, 2021 15:39

BurdetteLamar merged commit 28fb6d6 into ruby:master Dec 3, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding links to literals and Kernel #5192

Adding links to literals and Kernel #5192

BurdetteLamar commented Nov 29, 2021

esparta Nov 29, 2021

BurdetteLamar Nov 29, 2021

jeremyevans left a comment

jeremyevans Nov 29, 2021

BurdetteLamar Nov 29, 2021

jeremyevans Nov 29, 2021

BurdetteLamar Nov 29, 2021

jeremyevans Nov 29, 2021

BurdetteLamar Nov 29, 2021

jeremyevans Nov 29, 2021

BurdetteLamar Nov 29, 2021

esparta Nov 29, 2021

BurdetteLamar Nov 29, 2021

nobu Nov 29, 2021

jeremyevans Nov 29, 2021

BurdetteLamar Nov 30, 2021

jeremyevans Nov 30, 2021

BurdetteLamar Nov 30, 2021

BurdetteLamar Nov 30, 2021

nobu Dec 3, 2021

BurdetteLamar Dec 3, 2021

aycabta Dec 9, 2021

BurdetteLamar Dec 10, 2021

jeremyevans left a comment

BurdetteLamar commented Dec 1, 2021

	* - A {array literal}[doc/syntax/literals_rdoc.html#label-Array+Literals].
	* - An {array literal}[doc/syntax/literals_rdoc.html#label-Array+Literals].

		* - Instance method +to_i+, available in some Core and Standard Library classes.
		* - Instance method +to_int+, available in fewer classes.

Adding links to literals and Kernel #5192

Adding links to literals and Kernel #5192

Conversation

BurdetteLamar commented Nov 29, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeremyevans left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeremyevans left a comment

Choose a reason for hiding this comment

BurdetteLamar commented Dec 1, 2021