Project

General

Profile

Actions

Bug #6929

closed

Documentation for Ripper

Added by zzak (zzak _) over 11 years ago. Updated over 11 years ago.

Status:
Closed
Assignee:
Target version:
ruby -v:
2.0.0
Backport:
[ruby-core:47309]

Description

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

As always, feedback welcome.


Files

Updated by drbrain (Eric Hodel) over 11 years 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?

Updated by zzak (zzak _) over 11 years 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!

Updated by drbrain (Eric Hodel) over 11 years 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

Updated by zzak (zzak _) over 11 years ago

Hi Eric!

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

Updated by drbrain (Eric Hodel) over 11 years ago

This looks good, please commit it.

Updated by drbrain (Eric Hodel) over 11 years ago

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

Updated by zzak (zzak _) over 11 years 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] [ruby-core:47309]

Updated by Eregon (Benoit Daloze) over 11 years 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

+: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.

Updated by zzak (zzak _) over 11 years 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

Updated by Eregon (Benoit Daloze) over 11 years ago

Yes, that sounds good.

Updated by zzak (zzak _) over 11 years ago

Should I setup a new ticket for this?

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

Updated by Eregon (Benoit Daloze) over 11 years 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.

Updated by zzak (zzak _) over 11 years ago

Hello,

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

Updated by drbrain (Eric Hodel) over 11 years 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.

Actions #15

Updated by nagachika (Tomoyuki Chikanaga) over 11 years 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]],

Updated by zzak (zzak _) over 11 years ago

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

Actions

Also available in: Atom PDF

Like0
Like0Like0Like0Like0Like0Like0Like0Like0Like0Like0Like0Like0Like0Like0Like0Like0