0

I am writing a documentation for my Ruby on Rails 3.0.7 application using RDoc. In the application lib folder, I have the following:

module ModuleName
  class ModuleName::User < ActiveRecord::Base
    #'CONSTANT' documentation text
    CONSTANT = 'Test constant'

    #'method_name' documentation text
    def method_name
      ...
    end
  end
end

When I try to generate the documentation for the code above, RDoc will not parse the #'CONSTANT' documentation text and the #'method_name' documentation text, so the ouput documentation is blank.

1. How can I make RDoc to consider the commented code in the module "context"?

It doesn't help if I use the :doc: directive as follows:

module ModuleName #:doc:
  class ModuleName::User < ActiveRecord::Base #:doc:
    #'CONSTANT' documentation text
    CONSTANT = 'Test constant' #:doc:

    #'method_name' documentation text
    def method_name #:doc:
      ...
    end
  end
end

I note that I have these in the Class\Module Index:

ModuleName
ModuleName::ModuleName
ModuleName::ModuleName::ModuleName
ModuleName::ModuleName::ModuleName::User

2. What do they mean?

Paul Roub
  • 36,322
  • 27
  • 84
  • 93
user502052
  • 14,803
  • 30
  • 109
  • 188
  • try adding a space between the # and the actual comments. – Taryn East Jun 27 '11 at 08:29
  • @Taryn East - I already tryed that. – user502052 Jun 27 '11 at 09:15
  • Darn... and it seemed such a simple fix. – Taryn East Jun 27 '11 at 09:32
  • Ok, I just tried the exact same code and ran "rdoc" over it. It worked for me for both constant and 'method_name'. I also only got ModuleName and ModuleName::User. I'm using: RDoc V1.0.1 - 20041108 – Taryn East Jun 27 '11 at 09:36
  • But that was standard rdoc - not via rails. Just using a single class with that code in it. – Taryn East Jun 27 '11 at 09:38
  • How are you generating your rdoc? – Taryn East Jun 27 '11 at 09:38
  • I thing I am using RDoc 2 (see BTW 2 for more information) and I generate my code using the command: 'rake doc:app'... BTW 1: How can I generate the documentation using directly RDoc commands. BTW2: I use mac port... how can I know what RDoc version I am using? – user502052 Jun 27 '11 at 09:41
  • It won't be as pretty for your rails app as doing it the proper way - but it might be a good idea to test it with just the above code in a single ruby file... just to see if it gives the same output. – Taryn East Jun 27 '11 at 09:43
  • @Taryn East - I updated the above comment. However, what do you mean with ''? – user502052 Jun 27 '11 at 09:43
  • @Taryn East - I tryed to run 'rdoc user.rb' and it generates the documentatioin, but I get the same problem. It doesn't want to work as it should make! – user502052 Jun 27 '11 at 09:47
  • Ok, instead of running it over all of your user file, just create a new "test_this.rb" file or something and add *just* the code you've got as an example above. If it still fails - then it's something to do with rdoc. – Taryn East Jun 27 '11 at 09:49
  • and means "insert the name of your codefile here". – Taryn East Jun 27 '11 at 09:49
  • oh and remove all the spurious ":doc:"'s - it should work with just the one on the module. Adding the other ones isn't going to fix it... – Taryn East Jun 27 '11 at 09:51
  • OOC - which doc-file are you looking at to see if it worked? For me, the doc for the method/constant is in the doc for ModuleName::User – Taryn East Jun 27 '11 at 09:52
  • @Taryn East - OK, now it is a little bit more clear and it is fine: RDoc created for me class\model documentation for ModuleName, ModuleName::ModuleName, ModuleName::ModuleName::ModuleName, ModuleName::ModuleName::ModuleName::User. The documentation (that is, the commented text) is in the latter, but I still don't understand why it creates 4 files instead of 2. Can you help me to understand that? – user502052 Jun 27 '11 at 10:03
  • I'm not sure about that For me it only creates the two. Maybe it interprets the fact that you've nested ModuleName::User inside of the module ModuleName as actually being another level of module-ness. If you removed the ModuleName from in front of the class-name... it will just be "Class" nested inside of "ModuleName"... but I'm guessing. – Taryn East Jun 27 '11 at 10:20
  • @Taryn East - Thanks. BTW: I prevent to generate those 4 documentaion by removing the 'ModuleName' part from the 'ModuleName::User' statement. – user502052 Jun 27 '11 at 10:34

0 Answers0