ruby-core

In article <0AB6F24A-8BCB-11D8-B95B-000A95676A62@pragprog.com>,
  Dave Thomas <dave@pragprog.com> writes:

> The problem here is the RDoc currently interpreters :enddoc: as an 
> instruction to the container (either a top-level file or a 
> class/module). In this case, the top-level container (the file) has 
> been told not to document anything. However, when you say "class M::C", 
> RDoc is not documenting in the context of the container 'M', which has 
> not been told to end documenting. It therefore accepts the 
> documentation for the nested class 'C'.

I understand that RDoc maintains a documentation-enabling flag for
each container.

> I could change this behavior so that :enddoc: stopped _all_ future 
> documentation, but I'm not sure what the semantics should be.
>
> Any ideas?

I think the flag should inherit from an outer container's flag instead
of the previous state in the container last appeared.  In other words,
it should behave lexically.

The current non-lexical behavior makes curious result.

For example, M::C is documented if M is defined by module sentence but
not documented if M is defined by Module.new as follows.

% cat a.rb 
module M
end
# :enddoc:
class M::C 
  # documented
end

% cat b.rb 
M = Module.new
# :enddoc:
class M::C 
  # not documented
end

Another example is the flag is retained over multiple files.
With following files, rdoc a.rb b.rb generates documents for M and
M::C.  But rdoc b.rb a.rb generates a document for M::C3 too.

% cat a.rb 
module M
  class C1
  end
  # :enddoc:
  class C2
  end
end
% cat b.rb 
module M
  class C3
  end
end

The order sensitive behavior is not intuitive.
-- 
Tanaka Akira

Thread

Prev Next

In This Thread

Prev Next

ruby-core

Mailing Lists

[#2731] Re [ruby-dev:23297] new function for matching path name (and case sensitivity depends on system) — "H.Yamamoto" <ocean@...2.ccsnet.ne.jp>

[#2732] vflow 0.1a — jm <jm@...>

[#2745] Reworked SSL for POP patch — Daniel Hobe <daniel@...>

[#2748] Proposal: New Bignum — "Evan Webb" <evan@...>

[#2759] Re: Make clean runs autoconf — Ryan Davis <ryand-ruby@...>

[#2762] RDoc markup problem with \_abc_<i>def</i> — Tanaka Akira <akr@...17n.org>

[#2764] RDoc :enddoc: — Tanaka Akira <akr@...17n.org>

[#2766] RDoc generates a dangling hyperlink with :stopdoc without :startdoc: — Tanaka Akira <akr@...17n.org>

[#2774] Typo in gc.c 'descarding' should be 'discarding' [PATCH] — Eric Hodel <drbrain@...7.net>

[#2776] CSV changes — Dave Thomas <dave@...>

[#2781] CVS Question — "BH - Brad Coish" <BCoish@...>

[#2782] Problems with gsub, double quoted strings — Charles Mills <boson@...>

[#2783] typos in *.c RDoc comments — Doug Kearns <djkea2@...>

[#2784] Re: Problems with gsub, double quoted strings — george.marrows@...

[#2786] Possible bug in init_copy or rb_gc_copy_finalizer? — Ryan Davis <ryand-ruby@...>

[#2787] typos in lib/* RDoc comments — Doug Kearns <djkea2@...>

[#2788] Problems building ext/io/wait.c in 1.8 branch — Gavin Sinclair <gsinclair@...>

[#2789] STARTTLS support for net/smtp — "Daniel Hobe" <daniel@...>

[#2790] line tracing events — Markus Barchfeld <Markus.Barchfeld@...>

[#2793] BUG: segfault (with code) — Ryan Pavlik <rpav@...>

[#2805] Bug 1318 — Steven Jenkins <steven.jenkins@...>

[#2814] Tempfile strangeness in 1.9.0 — Steven Jenkins <steven.jenkins@...>

[#2819] File.join oddity ? — Johan Holmberg <holmberg@...>

[#2820] Re: File.join oddity ? — "Berger, Daniel" <djberge@...>

[#2825] ruby-mode.el indentation fix — George Ogata <g_ogata@...>

[#2827] — Jim Freeze <jim@...>

[#2829] lib/test/unit/testcase.rb — Mauricio Fern疣dez <batsman.geo@...>

[#2830] Bug in FileUtils - apathy or bad email — Jim Freeze <jim@...>

[#2832] Re: Bug in FileUtils - apathy or bad email — "Warren Brown" <WBrown@...>

[#2833] tcktklib.c patch — "Kent S." <ksibilev@...>

[#2834] rb_struct_new example needed — jm <jm@...>

Re: RDoc :enddoc:

Thread

In This Thread