rdoc: Change in #:nodoc: behaviour?

[Austin Ziegler]

It was recently pointed out to me that documentation for Text::Format
was missing from my website. I tracked this down to a change in
#:nodoc:

I have the following:

module Text #:nodoc:
# ri-documentation
class Format
end
end

In the past, this would generate documentation for Text::Format, but
not for Text -- which is simply a namespace for Text::Format in any
case.

Now, it prevents the documentation of Text::Format; removing the
#:nodoc: from the "module Text" line generates the documentation. This
is visible with the CVS HEAD version of Text::Format
pserver:[email protected]:/var/cvs/text-format, module
text-format).

-austin

 

[Dave Thomas]

It was recently pointed out to me that documentation for Text::Format
was missing from my website. I tracked this down to a change in
#:nodoc:

Please try the latest RDoc before reporting bugs. I know RDoc has lots
of them, but I'd rather not fix ones that are already fixed...


Cheers

Dave

 

[Austin Ziegler]

Please try the latest RDoc before reporting bugs. I know RDoc has lots
of them, but I'd rather not fix ones that are already fixed...

Unfortunately, for those of us who are not in a position to be able to
compile versions for ourselves, that's not always easy.

-austin

 

[Gavin Sinclair]

Unfortunately, for those of us who are not in a position to be able to
compile versions for ourselves, that's not always easy.

It would be nice to find a solution to this. First thing that comes
to mind: a project that makes the latest RDoc code available as a gem,
which installs under a different name than "rdoc", so it doesn't
clash.

Not a fantastic idea, I admit, but it might encourage other ideas.

Gavin

 

[James Britt]

Unfortunately, for those of us who are not in a position to be able to
compile versions for ourselves, that's not always easy.

Is there a list of fixed bugs, so that one can know that the problem has
been addressed before reporting it?

James

 

[Dave Thomas]

Unfortunately, for those of us who are not in a position to be able to
compile versions for ourselves, that's not always easy.

I understand that, and I apologize for the inconvenience. But RDoc is
now the same as any other standard Ruby library in that fixes are made
in the Ruby source tree.

James Britt:

Is there a list of fixed bugs, so that one can know that the problem
has been addressed before reporting it?

As with everything else in the standard Ruby distribution, I update the
Changelog whenever I make changes.

Gavin Sinclair:

It would be nice to find a solution to this. First thing that comes
to mind: a project that makes the latest RDoc code available as a gem,
which installs under a different name than "rdoc", so it doesn't
clash.

It'd be great if someone had the time to do this.

But then again, you could argue that the same should apply to the
interpreter itself---someone finds a bug, then they should be able to
get a fixed version of the interpreter without having to download from
the CVS and build... So perhaps this gem should be a complete Ruby
system (interpreter and libraries).


Cheers

Dave

 

[Hugh Sasse Staff Elec Eng]

James Britt:


As with everything else in the standard Ruby distribution, I update the
Changelog whenever I make changes.

Which seems to be here:

http://www.ruby-lang.org/cgi-bin/cvsweb.cgi/ruby/ChangeLog

in case someone was looking in the rdoc subdirectory, like me, for
eaxmple .

I don't see a way to select entries changed by a given person or
changes relating to a given subdirectory, but maybe that is what the
recent traffic here about the ruby changelog parser was about.

HTH
Hugh

 

[Gavin Sinclair]

It'd be great if someone had the time to do this.

But then again, you could argue that the same should apply to the
interpreter itself---someone finds a bug, then they should be able to
get a fixed version of the interpreter without having to download from
the CVS and build... So perhaps this gem should be a complete Ruby
system (interpreter and libraries).

Well, RDoc is the only component that truly feels this need, IMO.
Such a heavyweight gem, being the hack that it is, would be a bit
unwieldy.

But then there's the question of interactions between RDoc versions
and Ruby versions.

I think the best solution would be to have a webapp that accepts code
bundles (tgz or whatever) and RDocs them, showing the user the
results, then throwing away the code afterwards. This would run with
the more-or-less latest Ruby and RDoc, so you can see what it looks
like.

Any enterprising webapp programmers? Or any better ideas?

Gavin

 

[Dave Thomas]

Well, RDoc is the only component that truly feels this need, IMO.
Such a heavyweight gem, being the hack that it is, would be a bit
unwieldy.

Except...

Most of the things folks complain about require changes to the
documentation in the Ruby source tree: RDoc on its own is not that
useful.


Cheers

Dave

 

[Sam Roberts]

Quoteing (e-mail address removed), on Tue, Nov 30, 2004 at 09:01:51AM +0900:

Any enterprising webapp programmers? Or any better ideas?

rdoc is just ruby code, check it out of CVS, and dump into your ruby
lib/ directory. You don't need to recompile the ruby interpreter's c
code to upgrade rdoc.

I must be missing something, I don't get the problem.

Cheers,
Sam

 

[Tom Copeland]

I understand that, and I apologize for the inconvenience. But RDoc is
now the same as any other standard Ruby library in that fixes are made
in the Ruby source tree.

James Britt:

Reporting RDoc problems here might be good:

http://rubyforge.org/tracker/?atid=1698&group_id=426&func=browse

Then they can be tracked & searched and all that along with other
core/stdlib bugs...

Yours,

Tom