Bug #6929: Documentation for Ripper

• Status: Closed
• Assignee: zzak (zzak _)
• Target version: 2.0.0
• ruby -v: 2.0.0

[zzak (zzak _)]

I've added a patch to improve the documentation for the standard library Ripper.

As always, feedback welcome.

[drbrain (Eric Hodel)]

I think this is good overall.

No change should be necessary for extconf.rb or ext/ripper/tools as they are not included in ext/.document, can you check it?

[zzak (zzak _)]

ext/.document only lists ripper/lib and ripper/ripper.c (which doesn't exist)

I only added :nodoc: to ripper/tools and ripper/extconf.rb because those methods were showing up in documentation coverage report. I'm not sure how to use ext/.document with rdoc options, could you explain?

I'll put together another patch without the ripper/extconf.rb and ripper/tools stuff.

Thanks Eric!

[drbrain (Eric Hodel)]

=begin
When ((%make rdoc%)) runs it starts at the root and looks for ".document" files in the current directory. These files contain the paths that RDoc is allowed to traverse. Subdirectories may contain .document files, and ext/.document contains paths for ripper which expand to "ext/ripper/ripper.c" and "ext/ripper/lib".

If you run RDoc by hand you need to take into account the contents of the .document file. If you have:

rdoc ext/ripper

RDoc won't look in ext/.document or .document to determine which paths it should exclude or include. You need to run:

rdoc ext/ripper/ripper.c ext/ripper/lib

PS: Perhaps looking for .document files between the current directory and the source directory should be an option in RDoc
=end

[zzak (zzak _)]

• File 0002-Documentation-for-Ripper.patch 0002-Documentation-for-Ripper.patch added

Hi Eric!

Thanks for your feedback, I've added a patch sans the ripper/extconf.rb and ripper/tools changes as 0002-*

[drbrain (Eric Hodel)]

This looks good, please commit it.

[drbrain (Eric Hodel)]

• Assignee changed from drbrain (Eric Hodel) to zzak (zzak _)

[zzak (zzak _)]

• Status changed from Open to Closed
• % Done changed from 0 to 100

This issue was solved with changeset r36954.
Zachary, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.

---

• ext/ripper/lib/ripper.rb: Documentation for Ripper.
• ext/ripper/lib/ripper/lexer.rb: ditto.
• ext/ripper/lib/ripper/sexp.rb: ditto.
• ext/ripper/lib/ripper/filter.rb: ditto.
• ext/ripper/lib/ripper/core.rb: ditto.
  [Bug #6929] [ruby-core:47309]

[Eregon (Benoit Daloze)]

zzak: Good work!

Just a little note, when you say:
"# In our case, we're simply returning a String, so next we have the

+:void_stmt+ followed by a +:string_literal+."

The :void_stmt seems to be due only to the extra ";" in the code string.
Using 'def hello(world) "Hello, #{world}!"; end' won't produce the :void_stmt,
which I think is more of a parser artifact than it is meaningful in this context.

[zzak (zzak _)]

=begin
Eregon: Thank you for the feedback! Would you prefer the following instead?

(({# In our case, we're simply returning a String, so next we have the +:string_literal+ expression.}))

Then just leave out the extra semicolon from the example and explanation.
=end

[Eregon (Benoit Daloze)]

Yes, that sounds good.

[zzak (zzak _)]

Should I setup a new ticket for this?

On Thu, Sep 13, 2012 at 10:21 AM, Eregon (Benoit Daloze)
[e-mail] wrote:

Issue #6929 has been updated by Eregon (Benoit Daloze).

Yes, that sounds good.

Bug #6929: Documentation for Ripper
https://bugs.ruby-lang.org/issues/6929#change-29282

Author: zzak (Zachary Scott)
Status: Closed
Priority: Normal
Assignee: zzak (Zachary Scott)
Category: DOC
Target version: 2.0.0
ruby -v: 2.0.0

I've added a patch to improve the documentation for the standard library Ripper.

As always, feedback welcome.

--
http://bugs.ruby-lang.org/

[Eregon (Benoit Daloze)]

zzak (Zachary Scott) wrote:

Should I setup a new ticket for this?

I would say go ahead and commit it, as it's just a related and small fix.
It would be a nice to have drbrain's opinion, but I think we all agree for this.

[zzak (zzak _)]

Hello,

On Thu, Sep 13, 2012 at 2:25 PM, Eregon (Benoit Daloze)
[e-mail] wrote:

I would say go ahead and commit it, as it's just a related and small fix.
It would be a nice to have drbrain's opinion, but I think we all agree for this.

If there's no objection after a while I will commit it.

Thank you

[drbrain (Eric Hodel)]

As a documentation committer, feel free to commit documentation without making tickets unless you would like to get a review. I think you should commit this change.

[nagachika (Tomoyuki Chikanaga)]

Hello,

In r36992, sample output from Ripper.sexp seems not from current trunk version. doesn't it?

-# [:params, [[:@ident, "world", [1, 10]]], nil, nil, nil, nil]],
+# [:params, [[:@ident, "world", [1, 10]]], nil, nil, nil, nil, nil, nil]],

[zzak (zzak _)]

nagachika: That is correct. I just tried again on ruby-trunk, there are 6 +nil+s