From: Tanaka Akira <akr@...17n.org>
Date: 2004-04-12T17:18:04+09:00
Subject: Re: RDoc :enddoc:

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