=begin rdoc...=end block style problem when there's code before them

[mfn]

This is similar to https://github.com/rdoc/rdoc/issues/22 but I can't figure it out to be working in my case.

Using ruby 1.9.2p180 and rdoc 3.6.1. I see that https://github.com/rdoc/rdoc/issues/22 and https://github.com/rdoc/rdoc/pull/25 both were closed on April 13th and that 3.6.1 was last modified on May 16th ( https://github.com/rdoc/rdoc/commits/v3.6.1/ ), I also see the fix from the pull ( https://github.com/sgharms/rdoc/commit/e1451cd9396fb8b9692fd804066b6d66124de93f ) in my local version I've installed via gem.

Test case 1: rdoc for module is not generated

require 'something'
=begin rdoc
findmeindoc
=end
module Foo
    class Bar
    end
end

yeilds to

$ rm -Rf doc && rdoc -v test2.rb
Parsing sources...
100% [ 1/ 1]  test2.rb
  class Bar (undocumented)


Generating Darkfish format into ...

I.e. the module is ignored completely.

Removing the require line or moving it below the rdoc works:

=begin rdoc
findmeindoc
=end
require 'something'
module Foo
    class Bar
    end
end

yields to

$ rm -Rf doc && rdoc -v test3.rb
Parsing sources...
100% [ 1/ 1]  test3.rb
  class Foo::Bar (undocumented)
  module Foo (undocumented)

Similar, when I've two modules in a file, only the first one gets documented when using =begin and =end:

=begin rdoc
findmeindoc
=end
module Foo
end

=begin rdoc
findme2indoc
=end
module Frob
end

yields to

$ rm -Rf doc && rdoc -v test8.rb
Parsing sources...
100% [ 1/ 1]  test8.rb
  module Foo

[mfn]

It seems part of the problem is processing of newlines. When I put an empty line between rdoc and the module definition (from the first example), it works:

require 'something'
=begin rdoc
findmeindoc
=end

module Foo
    class Bar
    end
end

gives

$ rdoc -v test2.rb
Parsing sources...
100% [ 1/ 1]  test2.rb
  class Foo::Bar (undocumented)
  module Foo

[mfn]

When I modify the lexer to not consume the =end with the newline, it works:

$ diff -u ruby_lex.rb.orig ruby_lex.rb
--- ruby_lex.rb.orig    2011-05-31 02:46:43.000000000 +0200
+++ ruby_lex.rb 2011-05-31 02:46:50.000000000 +0200
@@ -409,6 +409,7 @@
       end

       gets # consume =end
+      ungetc

       @ltype = nil
       Token(TkCOMMENT, res)

Doesn't look like a clean fix though ...

[drbrain]

Thanks for the patch, it pointed me in th eright direction. Instead I changed the ruby parser to not assume that a TkCOMMENT is followed by a TkNL (newline).

Note that =begin and =end for documentation purposes is rarely used, commenting with # is preferred.