RDoc question

thomthom

hmm... Only class description can have spaced paragraphs? not methods?

thomthom

Wonder what a "<p>" would do?

Not mentioned in the RDoc docs. And I'd really not want to use that. Don't want to be using HTML markup in the comments.

I do seem to get paragraphs for class/module descriptions. But not methods...

thomthom

I'm wondering if my RDoc installation isn't all that good.

From this: http://rdoc.rubyforge.org/RDoc.html

@unknownuser said:

:call-seq:
Lines up to the next blank line in the comment are treated as the method’s calling sequence, overriding the default parsing of method parameters and yield arguments.

to me it only prints out ":call-seq:" ...

thomthom

hmm...

@unknownuser said:

C:\Users\Thomas>gem query

*** LOCAL GEMS ***

fxri (0.3.6)
fxruby (1.6.16)
hpricot (0.6.164)
log4r (1.0.5)
nokogiri (1.3.3)
ptools (1.1.6)
rake (0.8.1)
rdoc (2.4.3)
ruby-opengl (0.60.0)
test-unit (2.0.1)
win32-api (1.2.1, 1.2.0)
win32-clipboard (0.4.4)
win32-dir (0.3.2)
win32-eventlog (0.5.0)
win32-file (0.5.5)
win32-file-stat (1.3.1)
win32-process (0.5.9)
win32-sapi (0.1.4)
win32-sound (0.4.1)
windows-api (0.2.4)
windows-pr (0.9.3)

C:\Users\Thomas>

That matches the version number in the docs....

Chris Fullmer

Try it using the standard rDoc generator, instead of the fancy Darkfish one you used. See if that helps.

Chris

thomthom

Nooooooo! I was looking hard to find a more user friendly and better looking RDoc generator.

thomthom

Would this be correct to make an readme file be the index description: RDoc *.rb --main README.txt ??

thomthom

@chris fullmer said:

Try it using the standard rDoc generator, instead of the fancy Darkfish one you used. See if that helps.

Chris

Darkfish is what the latest RDoc is using.

Just tried to reinstall:


C;\Users\Thomas>gem install rdoc
Successfully installed rdoc-2.4.3
1 gem installed
Installing ri documentation for rdoc-2.4.3...
Updating ri class cache with 2246 classes...
Installing RDoc documentation for rdoc-2.4.3...

C;\Users\Thomas>

still not working...

Jim

I could never get rdoc to do what I want either.

Just some links..

Allison: http://blog.evanweaver.com/files/doc/fauna/allison/files/README.html

Hanna: http://github.com/mislav/hanna

webri (? no idea about this, but it looked relevant): http://webri.rubyforge.org/

thomthom

Trying out Allison - as it was frameless and had a nice quick filter feature. But I get errors trying to build the docs.


C;\Program Files (x86)\Google\Google SketchUp 7\Plugins\TT_Lib>allison *.rb --main README.txt --debu
g
--inline-source will be removed from RDoc on or after August 2009
Parsing sources with 2 thread(s)...
100% [14/14]  window.rb

Generating Darkfish...
could not find template "C;/Ruby/lib/ruby/gems/1.8/gems/allison-2.0.3/lib/allison"
C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;111;in `initialize'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;90;in `new'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;90;in `for'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/rdoc.rb;314;in `document'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/bin/rdoc;15
        C;/Ruby/bin/rdoc;19;in `load'
        C;/Ruby/bin/rdoc;19


C;\Program Files (x86)\Google\Google SketchUp 7\Plugins\TT_Lib>

In that folder there is:
allison.css allison.js allison.rb

thomthom

allison --path returns C:/Ruby/lib/ruby/gems/1.8/gems/allison-2.0.3/lib/allison
Seem to be missing .rb

So I tried rdoc *.rb --main README.txt --debug --template "C:/Ruby/lib/ruby/gems/1.8/gems/allison-2.0.3/lib/allison.rb"

but that resulted in

C;\Program Files (x86)\Google\Google SketchUp 7\Plugins\TT_Lib>rdoc *.rb --main README.txt --debug -
-template "C;/Ruby/lib/ruby/gems/1.8/gems/allison-2.0.3/lib/allison.rb"
Parsing sources with 2 thread(s)...
100% [14/14]  window.rb

Generating Darkfish...
could not find template "C;/Ruby/lib/ruby/gems/1.8/gems/allison-2.0.3/lib/allison.rb"
C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;111;in `initialize'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;90;in `new'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/generator/darkfish.rb;90;in `for'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/lib/rdoc/rdoc.rb;314;in `document'
        C;/Ruby/lib/ruby/gems/1.8/gems/rdoc-2.4.3/bin/rdoc;15
        C;/Ruby/bin/rdoc;19;in `load'
        C;/Ruby/bin/rdoc;19

I have no idea why. incompatible RDoc version?

thomthom

I installed Ruby on a secondary machine. I got the allison to work now. Seem that my ruby installation is a wee bit screwed up.

But the original rdoc does not support formatting for bold -italic- and underlined etc. and call-seq also isn't recognised.

thomthom

and updating rdoc causes the same loss of pragraphs etc... and still missing directive. and it broke the allison template.

ok. I think I might have to settle for original Rdoc, and use allison with less formatting options. but still wish the directives would work...

thomthom

makes so sense that I'm missing the formatting with the RDoc that comes with ruby. http://ruby-doc.org/core/ <- should be supported.

gaah. why is this not an easy operation?

thomthom

Found a solution: bye bye RDoc! Hello Yard!

YARD - A Ruby Documentation Tool

YARD is an extensible Ruby Documentation Tool (Yay!) for consistent documentation.

(yardoc.org)

Dan Rathbun

@unknownuser said:

Markup

The markup engine looks for a document’s natural left margin. This is used as the initial margin for the document.* Consecutive lines starting at this margin are considered to be a paragraph.

Does RDoc recognize \n ?

As in:
` # Returns an Array object.

\n

Added: 1.1.0

def to_a(orient_by_columns = false)`

or would that just produce "*n" ?

I think I have seen some markup in the standard ruby lib files that had <p></p> embedded.
_

thomthom

The missing paragraphs in Darkfish might just be due to it's CSS style. With the original RDoc they where there.

But it would not recognize various directives, couldn't find my README file.
The original seemed bugged, as in when you rebuilt it'd rebuild just the changed files, but you'd lose the existing in your index.
The exeprience is that it's abig mess.

While YARD just worked. Based on RDoc syntax, but with @tags.

Dan Rathbun

@thomthom said:

While YARD just worked. Based on RDoc syntax, but with @tags.

I'll have to bookmark that then. maybe it should go on the Sticky Links page?

thomthom

Maybe. Could be worth to test it first? I've only looked briefly on it, but over the weekend I hope to get time to document my TT_Lib library with it. Then I can say if I recommend it.
But I do like the sound of the @tags it has available. Appear to leave more control than plain RDoc. Such as parameter types and return types and version numbering.

Dan Rathbun

@thomthom said:

But I do like the sound of the @tags it has available. Appear to leave more control than plain RDoc. Such as parameter types and return types and version numbering.

It's sounding better all the time!

Keep us advised.