Bug #6929

Documentation for Ripper

Added by Zachary Scott over 1 year ago. Updated over 1 year ago.

[ruby-core:47309]
Status:Closed
Priority:Normal
Assignee:Zachary Scott
Category:doc
Target version:2.0.0
ruby -v:2.0.0 Backport:

Description

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

As always, feedback welcome.

0001-Documentation-for-Ripper.patch Magnifier (11.2 KB) Zachary Scott, 08/26/2012 02:34 AM

0002-Documentation-for-Ripper.patch Magnifier (8.14 KB) Zachary Scott, 08/31/2012 05:36 AM

Associated revisions

Revision 36954
Added by Zachary Scott over 1 year ago

  • 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]

Revision 36992
Added by Zachary Scott over 1 year ago

  • ext/ripper/lib/ripper.rb: Documentation for Ripper. +:void_stmt+ is meaningless [Bug #6929]

Revision 37008
Added by Zachary Scott over 1 year ago

  • ext/ripper/lib/ripper.rb: Match sample output to Ripper.sexp from current trunk version. [Bug #6929]

History

#1 Updated by Eric Hodel over 1 year ago

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?

#2 Updated by Zachary Scott over 1 year ago

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!

#3 Updated by Eric Hodel over 1 year ago

=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

#4 Updated by Zachary Scott over 1 year ago

Hi Eric!

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

#5 Updated by Eric Hodel over 1 year ago

This looks good, please commit it.

#6 Updated by Eric Hodel over 1 year ago

  • Assignee changed from Eric Hodel to Zachary Scott

#7 Updated by Zachary Scott over 1 year ago

  • 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]

#8 Updated by Benoit Daloze over 1 year ago

zzak: Good work!

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

The :voidstmt 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.

#9 Updated by Zachary Scott over 1 year ago

=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

#10 Updated by Benoit Daloze over 1 year ago

Yes, that sounds good.

#11 Updated by Zachary Scott over 1 year ago

Should I setup a new ticket for this?

On Thu, Sep 13, 2012 at 10:21 AM, Eregon (Benoit Daloze)
redmine@ruby-lang.org 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/

#12 Updated by Benoit Daloze over 1 year ago

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.

#13 Updated by Zachary Scott over 1 year ago

Hello,

On Thu, Sep 13, 2012 at 2:25 PM, Eregon (Benoit Daloze)
redmine@ruby-lang.org 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

#14 Updated by Eric Hodel over 1 year ago

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.

#15 Updated by Tomoyuki Chikanaga over 1 year ago

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]],

#16 Updated by Zachary Scott over 1 year ago

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

Also available in: Atom PDF