Bug #6929
closedDocumentation for Ripper
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) about 12 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 _) about 12 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) about 12 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 _) about 12 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) about 12 years ago
This looks good, please commit it.
Updated by drbrain (Eric Hodel) about 12 years ago
- Assignee changed from drbrain (Eric Hodel) to zzak (zzak _)
Updated by zzak (zzak _) about 12 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) about 12 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 _) about 12 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) about 12 years ago
Yes, that sounds good.
Updated by zzak (zzak _) about 12 years 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-29282Author: zzak (Zachary Scott)
Status: Closed
Priority: Normal
Assignee: zzak (Zachary Scott)
Category: DOC
Target version: 2.0.0
ruby -v: 2.0.0I've added a patch to improve the documentation for the standard library Ripper.
As always, feedback welcome.
Updated by Eregon (Benoit Daloze) about 12 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 _) about 12 years 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
Updated by drbrain (Eric Hodel) about 12 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.
Updated by nagachika (Tomoyuki Chikanaga) about 12 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 _) about 12 years ago
nagachika: That is correct. I just tried again on ruby-trunk, there are 6 +nil+s