Add code comments to ruby binding, and script to generate rdoc.

19 files changed, 1114 insertions, 11 deletions

diff --git a/ruby/check.cc b/ruby/check.cc
index b0a3615..eff3e9d 100644
--- a/ruby/check.cc
+++ b/ruby/check.cc
@@ -49,6 +49,12 @@ namespace
         return self;
     }
 
+    /*
+     * call-seq:
+     *     new(qualified_package_name, version_spec, environment_data)
+     *
+     * Creates a new EbuildCheckData for EbuildCheck.
+     */
     VALUE
     ebuild_check_data_new(int argc, VALUE *argv, VALUE self)
     {
@@ -78,6 +84,22 @@ namespace
         }
     }
 
+    /*
+     * Document-method: describe
+     *
+     * call-seq:
+     *     describe -> String
+     *
+     * Describe what check checks.
+     */
+    /*
+     * Document-method: is_important?
+     *
+     * call-seq:
+     *     is_important? -> true or false
+     *
+     * Is the check important?
+     */
     template <typename T_>
     struct CheckStruct
     {
@@ -114,6 +136,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     check(directory) -> CheckResult
+     *
+     * Runs check on directory.
+     */
     VALUE
     package_dir_check_check(VALUE self, VALUE f)
     {
@@ -127,6 +155,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     check(file) -> CheckResult
+     *
+     * Runs check on file.
+     */
     VALUE
     file_check_check(VALUE self, VALUE f)
     {
@@ -140,6 +174,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     check(ebuild_check_data) -> CheckResult
+     *
+     * Runs check on EbuildCheckData.
+     */
     VALUE
     ebuild_check_check(VALUE self, VALUE f)
     {
@@ -153,6 +193,14 @@ namespace
         }
     }
 
+    /*
+     * Document-method: keys
+     *
+     * call-seq:
+     *     keys -> Array
+     *
+     * Fetch the check names for this class.
+     */
     template <typename T_>
     struct CheckMakerStruct
     {
@@ -171,6 +219,12 @@ namespace
         }
     };
 
+    /*
+     * call-seq:
+     *     find_maker(name)
+     *
+     * Fetch the named check.
+     */
     VALUE package_dir_check_maker_find_maker(VALUE, VALUE maker)
     {
         try
@@ -184,6 +238,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     find_maker(name)
+     *
+     * Fetch the named check.
+     */
     VALUE file_check_maker_find_maker(VALUE, VALUE maker)
     {
         try
@@ -197,6 +257,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     find_maker(name)
+     *
+     * Fetch the named check.
+     */
     VALUE ebuild_check_maker_find_maker(VALUE, VALUE maker)
     {
         try
@@ -214,28 +280,54 @@ namespace
     {
         rb_require("singleton");
 
+        /*
+         * Document-class: Paludis::QA::EbuildCheckData
+         *
+         * A collection class for EbuildCheck.
+         */
         c_ebuild_check_data = rb_define_class_under(paludis_qa_module(), "EbuildCheckData", rb_cObject);
         rb_define_singleton_method(c_ebuild_check_data, "new", RUBY_FUNC_CAST(&ebuild_check_data_new),-1);
         rb_define_method(c_ebuild_check_data, "initialize", RUBY_FUNC_CAST(&ebuild_check_data_init),-1);
 
+        /*
+         * Document-class: Paludis::QA::PackageDirCheck
+         *
+         * A QA check that operates upon a package directory.
+         */
         c_package_dir_check = rb_define_class_under(paludis_qa_module(), "PackageDirCheck", rb_cObject);
         rb_funcall(c_package_dir_check, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_package_dir_check, "check", RUBY_FUNC_CAST(&package_dir_check_check),1);
         rb_define_method(c_package_dir_check, "describe", RUBY_FUNC_CAST(&CheckStruct<PackageDirCheck::Pointer>::describe),0);
         rb_define_method(c_package_dir_check, "is_important?", RUBY_FUNC_CAST(&CheckStruct<PackageDirCheck::Pointer>::is_important),0);
 
+        /*
+         * Document-class: Paludis::QA::FileCheck
+         *
+         * A QA check that operates upon a file.
+         */
         c_file_check = rb_define_class_under(paludis_qa_module(), "FileCheck", rb_cObject);
         rb_funcall(c_file_check, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_file_check, "check", RUBY_FUNC_CAST(&file_check_check),1);
         rb_define_method(c_file_check, "describe", RUBY_FUNC_CAST(&CheckStruct<FileCheck::Pointer>::describe),0);
         rb_define_method(c_file_check, "is_important?", RUBY_FUNC_CAST(&CheckStruct<FileCheck::Pointer>::is_important),0);
 
+        /*
+         * Document-class: Paludis::QA::EbuildCheck
+         *
+         * Base class for QA checks that operate upon ebuilds.
+         */
         c_ebuild_check = rb_define_class_under(paludis_qa_module(), "EbuildCheck", rb_cObject);
         rb_funcall(c_ebuild_check, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_ebuild_check, "check", RUBY_FUNC_CAST(&ebuild_check_check),1);
         rb_define_method(c_ebuild_check, "describe", RUBY_FUNC_CAST(&CheckStruct<EbuildCheck::Pointer>::describe),0);
         rb_define_method(c_ebuild_check, "is_important?", RUBY_FUNC_CAST(&CheckStruct<EbuildCheck::Pointer>::is_important),0);
 
+        /*
+         * Document-class: Paludis::QA::PackageDirCheckMaker
+         *
+         * Class to access PackageDirChecks
+         *
+         */
         c_package_dir_check_maker = rb_define_class_under(paludis_qa_module(), "PackageDirCheckMaker", rb_cObject);
         rb_funcall(c_package_dir_check_maker, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_funcall(rb_const_get(rb_cObject, rb_intern("Singleton")), rb_intern("included"), 1, c_package_dir_check_maker);
@@ -244,6 +336,12 @@ namespace
         rb_define_alias(c_package_dir_check_maker, "check_names", "keys");
         rb_define_alias(c_package_dir_check_maker, "find_check", "find_maker");
 
+        /*
+         * Document-class: Paludis::QA::FileCheckMaker
+         *
+         * Class to access FileChecks
+         *
+         */
         c_file_check_maker = rb_define_class_under(paludis_qa_module(), "FileCheckMaker", rb_cObject);
         rb_funcall(c_file_check_maker, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_funcall(rb_const_get(rb_cObject, rb_intern("Singleton")), rb_intern("included"), 1, c_file_check_maker);
@@ -252,6 +350,12 @@ namespace
         rb_define_alias(c_file_check_maker, "check_names", "keys");
         rb_define_alias(c_file_check_maker, "find_check", "find_maker");
 
+        /*
+         * Document-class: Paludis::QA::EbuildCheckMaker
+         *
+         * Class to access EbuildChecks
+         *
+         */
         c_ebuild_check_maker = rb_define_class_under(paludis_qa_module(), "EbuildCheckMaker", rb_cObject);
         rb_funcall(c_ebuild_check_maker, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_funcall(rb_const_get(rb_cObject, rb_intern("Singleton")), rb_intern("included"), 1, c_ebuild_check_maker);
diff --git a/ruby/check_result.cc b/ruby/check_result.cc
index 34b4873..2ced140 100644
--- a/ruby/check_result.cc
+++ b/ruby/check_result.cc
@@ -63,6 +63,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     empty? -> true of false
+     *
+     * Are there any messages?
+     */
     VALUE
     check_result_empty(VALUE self)
     {
@@ -71,6 +77,12 @@ namespace
         return (ptr)->empty() ? Qtrue : Qfalse;
     }
 
+    /*
+     * call-seq:
+     *     most_severe_level -> QALevel
+     *
+     * Most severe message level in the CheckResult.
+     */
     VALUE
     check_result_most_severe_level(VALUE self)
     {
@@ -96,6 +108,12 @@ namespace
 
     }
 
+    /*
+     * call-seq:
+     *     messages -> Array
+     *
+     * Array with all result Messages in.
+     */
     VALUE
     check_result_messages(VALUE self)
     {
@@ -108,6 +126,22 @@ namespace
         return result;
     }
 
+    /*
+     * Document-method: item
+     *
+     * call-seq:
+     *     item -> String
+     *
+     * What was checked
+     */
+    /*
+     * Document-method: rule
+     *
+     * call-seq:
+     *     rule -> String
+     *
+     * Check class that produced this result.
+     */
     template <const std::string & (CheckResult::* m_) () const>
     struct CheckResultValue
     {
@@ -122,6 +156,11 @@ namespace
 
     void do_register_check_result()
     {
+        /*
+         * Document-class: Paludis::QA::CheckResult
+         *
+         * The result of a QA check.
+         */
         c_check_result = rb_define_class_under(paludis_qa_module(), "CheckResult", rb_cObject);
         rb_define_singleton_method(c_check_result, "new", RUBY_FUNC_CAST(&check_result_new),-1);
         rb_define_method(c_check_result, "initialize", RUBY_FUNC_CAST(&check_result_init),-1);
diff --git a/ruby/contents.cc b/ruby/contents.cc
index dc6bd87..7290c3b 100644
--- a/ruby/contents.cc
+++ b/ruby/contents.cc
@@ -59,6 +59,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     add(contents_entry)
+     *
+     * Add a new entry.
+    */
     VALUE contents_add(VALUE self, VALUE v)
     {
         if (rb_obj_is_kind_of(v, c_contents_entry))
@@ -84,6 +90,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     entries -> Array
+     *
+     * Gets an array of entries.
+     */
     VALUE
     contents_entries(VALUE self)
     {
@@ -155,6 +167,16 @@ namespace
         }
     }
 
+    /*
+     * Document-method: name
+     *
+     * Returns our name
+     */
+    /*
+     * Document-method: target
+     *
+     * Returns the target
+     */
     template <typename T_, std::string (T_::* m_) () const>
     struct ContentsThings
     {
@@ -169,27 +191,59 @@ namespace
 
     void do_register_contents()
     {
+        /*
+         * Document-class: Paludis::Contents
+         *
+         * A package's contents.
+         */
         c_contents = rb_define_class_under(paludis_module(), "Contents", rb_cObject);
         rb_define_singleton_method(c_contents, "new", RUBY_FUNC_CAST(&contents_new), 0);
         rb_define_method(c_contents, "initialize", RUBY_FUNC_CAST(&contents_init), 0);
         rb_define_method(c_contents, "entries", RUBY_FUNC_CAST(&contents_entries), 0);
         rb_define_method(c_contents, "add", RUBY_FUNC_CAST(&contents_add), 1);
 
+        /*
+         * Document-class: Paludis::ContentsEntry
+         *
+         * Base class for a ContentsEntry
+         */
         c_contents_entry = rb_define_class_under(paludis_module(), "ContentsEntry", rb_cObject);
         rb_funcall(c_contents_entry, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_contents_entry, "name", RUBY_FUNC_CAST((&ContentsThings<ContentsEntry,&ContentsEntry::name>::fetch)), 0);
         rb_define_method(c_contents_entry, "initialize", RUBY_FUNC_CAST(&contents_entry_init),-1);
         rb_define_method(c_contents_entry, "to_s", RUBY_FUNC_CAST(&Common<ContentsEntry::ConstPointer>::to_s_via_ptr), 0);
 
+        /*
+         * Document-class: Paludis::ContentsFileEntry
+         *
+         * A file ContentsEntry
+         */
         c_contents_file_entry = rb_define_class_under(paludis_module(), "ContentsFileEntry", c_contents_entry);
         rb_define_singleton_method(c_contents_file_entry, "new", RUBY_FUNC_CAST((&ContentsNew<ContentsFileEntry>::contents_entry_new)), -1);
+
+        /*
+         * Document-class: Paludis::ContentsDirEntry
+         *
+         * A directory ContentsEntry
+         */
         c_contents_dir_entry = rb_define_class_under(paludis_module(), "ContentsDirEntry", c_contents_entry);
         rb_define_singleton_method(c_contents_dir_entry, "new", RUBY_FUNC_CAST((&ContentsNew<ContentsDirEntry>::contents_entry_new)), -1);
+
+        /*
+         * Document-class: Paludis::ContentsMiscEntry
+         
+         *  A miscellaneous ContentsEntry
+         */
         c_contents_misc_entry = rb_define_class_under(paludis_module(), "ContentsMiscEntry", c_contents_entry);
         rb_define_singleton_method(c_contents_misc_entry, "new", RUBY_FUNC_CAST((&ContentsNew<ContentsMiscEntry>::contents_entry_new)), -1);
+
+        /*
+         * Document-class: Paludis::ContentsSymEntry
+         *
+         * A symlink ContentsEntry
+         */
         c_contents_sym_entry = rb_define_class_under(paludis_module(), "ContentsSymEntry", c_contents_entry);
         rb_define_singleton_method(c_contents_sym_entry, "new", RUBY_FUNC_CAST(&contents_sym_entry_new), -1);
-        rb_define_method(c_contents_sym_entry, "to_s", RUBY_FUNC_CAST(&Common<ContentsSymEntry::ConstPointer>::to_s_via_ptr), 0);
         rb_define_method(c_contents_sym_entry, "target", RUBY_FUNC_CAST((&ContentsThings<ContentsSymEntry,&ContentsSymEntry::target>::fetch)), 0);
     }
 }
diff --git a/ruby/create_ruby_doc.rb b/ruby/create_ruby_doc.rb
new file mode 100644
index 0000000..74554d9
--- /dev/null
+++ b/ruby/create_ruby_doc.rb
@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+# vim: set sw=4 sts=4 et tw=80 :
+
+require 'rdoc/rdoc'
+
+module RDoc
+    #define these ourself, as they are in all files.
+#    KNOWN_CLASSES['rb_mPaludis'] = 'Paludis'
+#    KNOWN_CLASSES['rb_mQA'] = 'Paludis::QA'
+#    KNOWN_CLASSES['c_environment'] = 'Paludis::Environment'
+
+    class C_Parser_Paludis < C_Parser
+        #override C_Parse
+        parse_files_matching(/\.(c|cc|cpp|CC)$/)
+
+        def initialize(top_level, file_name, body, options, stats)
+            #Paludis and Paludis::QA are already added
+            body.gsub!('paludis_module()','c_paludis_module')
+ #           body.gsub!('c_paludis_module','rb_mPaludis')
+            body.gsub!('paludis_qa_module()','c_paludis_qa_module')
+  #          body.gsub!('c_paludis_qa_module','rb_mQA')
+            body.gsub!('environment_class()','c_environment')
+#            body.gsub!('paludis_qa_module()','rb_mQA')
+
+            #parse_c hates rb_defines over multiple lines
+            body.gsub!(/(rb_define[^;]+)\n/)  {|match| $1}
+            new_body=''
+            new_body += "\n" + 'c_paludis_module = rb_define_module("Paludis");' + "\n"
+            new_body += 'c_paludis_qa_module = rb_define_module_under(c_paludis_module, "QA");' + "\n"
+            new_body += 'c_environment = rb_define_class_under(c_paludis_module, "Environment", rb_cObject);' + "\n"
+            body.each_line do |line|
+                next if line =~ /rb_mPaludis\s*=/
+                next if line =~ /rb_mQA\s*=/
+                next if line =~ /c_environment\s*=/
+                if line =~ /cc_enum_special/
+                    line.scan(/cc_enum_special<([^,]+),\s*([^,]+),\s*([^>]+)>/) do
+                        |header_file, type, in_class|
+                        new_body+= generate_consts(header_file, type, in_class)
+                    end
+                    next
+                end
+                if line =~ /rb_define/
+                    #help rdoc recognise normal methods
+                    line.gsub!('&','')
+                    line.gsub!(/RUBY_FUNC_CAST\(*([^)]+)\)*/) {|match| $1}
+                    #help rdoc recognise template methods
+                    line.gsub!(/\w+<\s*\w+(::\w+)*(,\s*\w+)*(::\w+)?>::\w+/,'template_methods')
+                end
+                new_body+= line
+            end
+            #puts new_body
+            #exit
+            super(top_level, file_name, new_body, options, stats)
+        end
+
+        def scan
+            x = super
+            puts x.file_relative_name
+            x
+        end
+
+        def generate_consts(header, type, in_class)
+            consts = []
+            file = IO.readlines("../#{header}").join("").gsub(%r{//.*$},'').gsub(/\s+/,'')
+            if file =~ /enum#{type}\{([^}]+)\}/
+                i = 0
+                $1.split(',').each do |line|
+                    next if line =~/last/
+                    const =  line.sub(%r{^[^_]+_},'').capitalize #strip start
+                    const.gsub!(%r{_(\w)}) { |x| $1.capitalize}
+                    consts << "rb_define_const(#{in_class}, \"#{const}\", #{i});"
+                    i+=1
+                end
+            end
+            consts.join("\n")
+        end
+    end
+end
+begin
+  r = RDoc::RDoc.new
+  r.document(ARGV)
+rescue RDoc::RDocError => e
+  $stderr.puts e.message
+  exit(1)
+end
diff --git a/ruby/dep_atom.cc b/ruby/dep_atom.cc
index 65cac07..f7b8660 100644
--- a/ruby/dep_atom.cc
+++ b/ruby/dep_atom.cc
@@ -94,6 +94,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     blocked_atom -> DepAtom
+     *
+     * Fetch the DepAtom we're blocking.
+     */
     VALUE
     block_dep_atom_blocked_atom(VALUE self)
     {
@@ -124,6 +130,12 @@ namespace
         }
     };
 
+    /*
+     * call-seq:
+     *     flag -> String
+     *
+     * Fetch our use flag name.
+     */
     VALUE
     use_dep_atom_flag(VALUE self)
     {
@@ -132,6 +144,12 @@ namespace
         return rb_str_new2(stringify((*p)->flag()).c_str());
     }
 
+    /*
+     * call-seq:
+     *     inverse? -> true or false
+     *
+     * Fetch whether we are a ! flag.
+     */
     VALUE
     use_dep_atom_inverse(VALUE self)
     {
@@ -140,6 +158,11 @@ namespace
         return (*p)->inverse() ? Qtrue : Qfalse;
     }
 
+    /*
+     * call-seq: each {|atom| block }
+     *
+     * Iterate over each child DepAtom.
+     */
     VALUE
     composite_dep_atom_each(VALUE self)
     {
@@ -152,38 +175,85 @@ namespace
 
     void do_register_dep_atom()
     {
+        /*
+         * Document-class: Paludis::DepAtom
+         *
+         * Base class for a dependency atom.
+         */
         c_dep_atom = rb_define_class_under(paludis_module(), "DepAtom", rb_cObject);
         rb_funcall(c_dep_atom, rb_intern("private_class_method"), 1, rb_str_new2("new"));
 
+        /*
+         * Document-class: Paludis::CompositeDepAtom
+         *
+         * Class for dependency atoms that have a number of child dependency atoms.
+         */
         c_composite_dep_atom = rb_define_class_under(paludis_module(), "CompositeDepAtom", c_dep_atom);
         rb_funcall(c_composite_dep_atom, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_composite_dep_atom, "each", RUBY_FUNC_CAST(&composite_dep_atom_each), 0);
         rb_include_module(c_composite_dep_atom, rb_mEnumerable);
 
+        /*
+         * Document-class: Paludis::AllDepAtom
+         *
+         * Represents a ( first second third ) or top level group of dependency atoms.
+         */
         c_all_dep_atom = rb_define_class_under(paludis_module(), "AllDepAtom", c_composite_dep_atom);
         rb_funcall(c_all_dep_atom, rb_intern("private_class_method"), 1, rb_str_new2("new"));
 
+        /*
+         * Document-class: Paludis::AnyDepAtom
+         *
+         * Represents a "|| ( )" dependency block.
+         */
         c_any_dep_atom = rb_define_class_under(paludis_module(), "AnyDepAtom", c_composite_dep_atom);
         rb_funcall(c_any_dep_atom, rb_intern("private_class_method"), 1, rb_str_new2("new"));
 
+        /*
+         * Document-class: Paludis::UseDepAtom
+         *
+         * Represents a use? ( ) dependency atom.
+         */
         c_use_dep_atom = rb_define_class_under(paludis_module(), "UseDepAtom", c_composite_dep_atom);
         rb_funcall(c_use_dep_atom, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_use_dep_atom, "flag", RUBY_FUNC_CAST(&use_dep_atom_flag), 0);
         rb_define_method(c_use_dep_atom, "inverse?", RUBY_FUNC_CAST(&use_dep_atom_inverse), 0);
 
+        /*
+         * Document-class: Paludis::StringDepAtom
+         *
+         * A StringDepAtom represents a non-composite dep atom with an associated piece of text.
+         */
         c_string_dep_atom = rb_define_class_under(paludis_module(), "StringDepAtom", c_dep_atom);
         rb_funcall(c_string_dep_atom, rb_intern("private_class_method"), 1, rb_str_new2("new"));
 
+        /*
+         * Document-class: Paludis::PackageDepAtom
+         *
+         * A PackageDepAtom represents a package name (for example, 'app-editors/vim'),
+         * possibly with associated version and SLOT restrictions.
+         */
         c_package_dep_atom = rb_define_class_under(paludis_module(), "PackageDepAtom", c_string_dep_atom);
         rb_define_singleton_method(c_package_dep_atom, "new", RUBY_FUNC_CAST(&DepAtomThings<PackageDepAtom>::dep_atom_new_1), 1);
         rb_define_method(c_package_dep_atom, "initialize", RUBY_FUNC_CAST(&dep_atom_init_1), 1);
         rb_define_method(c_package_dep_atom, "to_s", RUBY_FUNC_CAST(&Common<PackageDepAtom::ConstPointer>::to_s_via_ptr), 0);
 
+        /*
+         * Document-class: Paludis::PlainTextDepAtom
+         *
+         * A PlainTextDepAtom represents a plain text entry (for example, a URI in SRC_URI).
+         */
         c_plain_text_dep_atom = rb_define_class_under(paludis_module(), "PlainTextDepAtom", c_string_dep_atom);
         rb_define_singleton_method(c_plain_text_dep_atom, "new", RUBY_FUNC_CAST(&DepAtomThings<PlainTextDepAtom>::dep_atom_new_1), 1);
         rb_define_method(c_plain_text_dep_atom, "initialize", RUBY_FUNC_CAST(&dep_atom_init_1), 1);
         rb_define_method(c_plain_text_dep_atom, "to_s", RUBY_FUNC_CAST(&Common<PlainTextDepAtom::ConstPointer>::to_s_via_ptr), 0);
 
+        /*
+         * Document-class: Paludis::BlockDepAtom
+         *
+         * A BlockDepAtom represents a block on a package name (for example, 'app-editors/vim'), possibly with
+         * associated version and SLOT restrictions.
+         */
         c_block_dep_atom = rb_define_class_under(paludis_module(), "BlockDepAtom", c_string_dep_atom);
         rb_define_singleton_method(c_block_dep_atom, "new", RUBY_FUNC_CAST(&block_dep_atom_new), 1);
         rb_define_method(c_block_dep_atom, "initialize", RUBY_FUNC_CAST(&dep_atom_init_1), 1);
diff --git a/ruby/environment.cc b/ruby/environment.cc
index 8ce34b2..dcd5637 100644
--- a/ruby/environment.cc
+++ b/ruby/environment.cc
@@ -35,6 +35,13 @@ namespace
     static VALUE c_default_config;
     static VALUE c_no_config_environment;
 
+    /*
+     * call-seq:
+     *     query_use(use_flag)
+     *     query_use(use_flag, package_database_entry)
+     *
+     * Does the user want the specified USE flag set, either globally or for a PackageDatabaseEntry.
+     */
     VALUE
     environment_query_use(int argc, VALUE * argv, VALUE self)
     {
@@ -59,6 +66,13 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     accept_keyword(keyword)
+     *     accept_keyword(keyword, package_database_entry)
+     *
+     * Is the specified KEYWORD set, either globally or for a PackageDatabaseEntry.
+     */
     VALUE
     environment_accept_keyword(int argc, VALUE * argv, VALUE self)
     {
@@ -83,6 +97,13 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     accept_license(license)
+     *     accept_license(license, package_database_entry)
+     *
+     * Is the specified LICENSE set, either globally or for a PackageDatabaseEntry.
+     */
     VALUE
     environment_accept_license(int argc, VALUE * argv, VALUE self)
     {
@@ -107,6 +128,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     mask_reasons(package_database_entry)
+     *
+     * Fetch the MaskReasons for a PackageDatabaseEntry.
+     */
     VALUE
     environment_mask_reasons(VALUE self, VALUE pde_value)
     {
@@ -125,6 +152,9 @@ namespace
         }
     }
 
+    /*
+     * Fetch our PackageDatabase.
+     */
     VALUE
     environment_package_database(VALUE self)
     {
@@ -141,6 +171,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     package_set(set_name)
+     *
+     * Fetch a named package set as a DepAtom.
+     */
     VALUE
     environment_package_set(VALUE self, VALUE set_name)
     {
@@ -157,6 +193,9 @@ namespace
         }
     }
 
+    /*
+     * Gets the config suffix.
+     */
     VALUE
     default_config_config_suffix(VALUE)
     {
@@ -170,6 +209,21 @@ namespace
         }
     }
 
+    /*
+     * Document-method: root
+     *
+     * The ROOT.
+     */
+    /*
+     * Document-method: bashrc_files
+     *
+     * Our bashrc files.
+     */
+    /*
+     * Document-method: config_dir
+     *
+     * The config directory.
+     */
     template <std::string (DefaultConfig::* m_) () const>
     struct ConfigStruct
     {
@@ -180,6 +234,12 @@ namespace
         }
     };
 
+    /*
+     * call-seq:
+     *     config_suffix=
+     *
+     * Set config suffig.
+     */
     VALUE
     default_config_config_suffix_set(VALUE klass, VALUE str)
     {
@@ -200,6 +260,12 @@ namespace
         return self;
     }
 
+    /*
+     * call-seq:
+     *     new(dir)
+     *
+     * Create a new NoConfigEnvironment form the specified directory.
+     */
     VALUE
     no_config_environment_new(VALUE self, VALUE s)
     {
@@ -249,6 +315,12 @@ namespace
     void do_register_environment()
     {
         rb_require("singleton");
+        /*
+         * Document-class: Paludis::Environment
+         *
+         * Represents a working environment, which contains an available packages database and provides 
+         * various methods for querying package visibility and options.
+         */
         c_environment = environment_class();
         rb_funcall(c_environment, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_environment, "query_use", RUBY_FUNC_CAST(&environment_query_use), -1);
@@ -258,10 +330,22 @@ namespace
         rb_define_method(c_environment, "package_database", RUBY_FUNC_CAST(&environment_package_database), 0);
         rb_define_method(c_environment, "package_set", RUBY_FUNC_CAST(&environment_package_set), 1);
 
+        /*
+         * Document-class: Paludis::DefaultEnvironment
+         *
+         * The DefaultEnvironment is an Environment that correspons to the normal operating environment
+         *
+         */
         c_default_environment = rb_define_class_under(paludis_module(), "DefaultEnvironment", c_environment);
         rb_define_singleton_method(c_default_environment, "new", RUBY_FUNC_CAST(&default_environment_new), 0);
         rb_funcall(rb_const_get(rb_cObject, rb_intern("Singleton")), rb_intern("included"), 1, c_default_environment);
 
+
+        /*
+         * Document-class: Paludis::DefaultConfig
+         *
+         * DefaultConfig is used by DefaultEnvironment to access the user's configuration settings from on-disk configuration files.
+         */
         c_default_config = rb_define_class_under(paludis_module(), "DefaultConfig", rb_cObject);
         rb_funcall(c_default_config, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_funcall(rb_const_get(rb_cObject, rb_intern("Singleton")), rb_intern("included"), 1, c_default_config);
@@ -273,6 +357,11 @@ namespace
         rb_define_method(c_default_config, "root", RUBY_FUNC_CAST((&ConfigStruct<&DefaultConfig::root>::fetch)), 0);
         rb_define_method(c_default_config, "bashrc_files", RUBY_FUNC_CAST((&ConfigStruct<&DefaultConfig::bashrc_files>::fetch)), 0);
 
+        /*
+         * Document-class: Paludis::NoConfigEnvironment
+         *
+         * An environment that uses a single repository, with no user configuration.
+         */
         c_no_config_environment = rb_define_class_under(paludis_module(), "NoConfigEnvironment", c_environment);
         rb_define_singleton_method(c_no_config_environment, "new", RUBY_FUNC_CAST(&no_config_environment_new), 1);
         rb_define_method(c_no_config_environment, "initialize", RUBY_FUNC_CAST(&no_config_environment_init), 1);
diff --git a/ruby/log.cc b/ruby/log.cc
index 2940b1a..230325c 100644
--- a/ruby/log.cc
+++ b/ruby/log.cc
@@ -31,12 +31,24 @@ namespace
     static VALUE c_log;
     static VALUE c_log_level;
 
+    /*
+     * call-seq:
+     *     log_level -> LogLevel
+     *
+     * Fetch the current log level.
+     */
     VALUE
     log_log_level(VALUE)
     {
         return INT2FIX(Log::get_instance()->log_level());
     }
 
+    /*
+     * call-seq:
+     *     log_level=
+     *
+     * Only display messages of at least this level.
+     */
     VALUE
     log_log_level_set(VALUE self, VALUE value)
     {
@@ -47,6 +59,12 @@ namespace
         return self;
     }
 
+    /*
+     * call-seq:
+     *     set_program_name(name)
+     *
+     * Set our program name.
+     */
     VALUE
     log_set_program_name(VALUE self, VALUE name)
     {
@@ -54,6 +72,12 @@ namespace
         return self;
     }
 
+    /*
+     * call-seq:
+     *     message(log_level, message)
+     *
+     * Log a message at the specified level.
+     */
     VALUE
     log_message(VALUE self, VALUE log_level, VALUE message)
     {
@@ -69,6 +93,11 @@ namespace
     {
         rb_require("singleton");
 
+        /*
+         * Document-class: Paludis::Log
+         *
+         * Singleton class that handles log messages.
+         */
         c_log = rb_define_class_under(paludis_module(), "Log", rb_cObject);
         rb_funcall(rb_const_get(rb_cObject, rb_intern("Singleton")), rb_intern("included"), 1, c_log);
         rb_define_method(c_log, "log_level", RUBY_FUNC_CAST(&log_log_level), 0);
@@ -80,6 +109,8 @@ namespace
         for (LogLevel l(static_cast<LogLevel>(0)), l_end(last_ll) ; l != l_end ;
                 l = static_cast<LogLevel>(static_cast<int>(l) + 1))
             rb_define_const(c_log_level, value_case_to_RubyCase(stringify(l)).c_str(), INT2FIX(l));
+
+        // cc_enum_special<paludis/util/log.hh, LogLevel, c_log_level>
     }
 }
 
diff --git a/ruby/mask_reasons.cc b/ruby/mask_reasons.cc
index 7d647b6..1500159 100644
--- a/ruby/mask_reasons.cc
+++ b/ruby/mask_reasons.cc
@@ -55,6 +55,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     each {|mask_reason| block }
+     *
+     * Iterate through the mask reasons.
+     */
     VALUE
     mask_reasons_each(VALUE self)
     {
@@ -67,6 +73,12 @@ namespace
         return self;
     }
 
+    /*
+     * call-seq:
+     *     empty? -> true or false
+     *
+     * Is the collection empty.
+     */
     VALUE
     mask_reasons_empty(VALUE self)
     {
@@ -78,6 +90,11 @@ namespace
 
     void do_register_mask_reasons()
     {
+        /*
+         * Document-class: Paludis::MaskReasons
+         *
+         * A collection of reasons for why a package is masked.
+         */
         c_mask_reasons = rb_define_class_under(paludis_module(), "MaskReasons", rb_cObject);
         rb_define_singleton_method(c_mask_reasons, "new", RUBY_FUNC_CAST(&mask_reasons_new), 0);
         rb_define_method(c_mask_reasons, "initialize", RUBY_FUNC_CAST(&mask_reasons_init), 0);
diff --git a/ruby/message.cc b/ruby/message.cc
index 7903e99..f7dd3c6 100644
--- a/ruby/message.cc
+++ b/ruby/message.cc
@@ -66,7 +66,12 @@ namespace
             exception_to_ruby_exception(e);
         }
     }
-
+    /*
+     * call-seq:
+     *     msg
+     *
+     * Message value.
+     */
     VALUE
     message_msg(VALUE self)
     {
@@ -75,6 +80,12 @@ namespace
         return rb_str_new2((ptr)->msg.c_str());
     }
 
+    /*
+     * call-seq:
+     *     level
+     *
+     * Message level.
+     */
     VALUE
     message_level(VALUE self)
     {
@@ -84,11 +95,22 @@ namespace
     }
     void do_register_message()
     {
+        /* Document-module: Paludis::QA::QALevel
+         *
+         * This module contains QALevel constants.
+         *
+         */
         c_qa_level = rb_define_module_under(paludis_qa_module(), "QALevel");
         for (QALevel l(static_cast<QALevel>(0)), l_end(last_qal) ; l != l_end ;
                 l = static_cast<QALevel>(static_cast<int>(l) + 1))
             rb_define_const(c_qa_level, value_case_to_RubyCase(stringify(l)).c_str(), INT2FIX(l));
 
+        // cc_enum_special<paludis/qa/message.hh, QALevel, c_qa_level>
+
+        /* Document-class: Paludis::QA::Message
+         *
+         * A QA message
+         */
         c_message = rb_define_class_under(paludis_qa_module(), "Message", rb_cObject);
         rb_define_singleton_method(c_message, "new", RUBY_FUNC_CAST(&message_new),-1);
         rb_define_method(c_message, "initialize", RUBY_FUNC_CAST(&message_init),-1);
diff --git a/ruby/metadata_file.cc b/ruby/metadata_file.cc
index ffd648b..55ffad8 100644
--- a/ruby/metadata_file.cc
+++ b/ruby/metadata_file.cc
@@ -68,6 +68,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     herds -> Array
+     *
+     * Array of herds specified in file.
+     */
     VALUE
     metadata_file_herds(VALUE self)
     {
@@ -81,6 +87,12 @@ namespace
         return result;
     }
 
+    /*
+     * call-seq:
+     *     maintainers -> Hash
+     *
+     * Hash of maintainers specified in file, keys are :email and :name.
+     */
     VALUE
     metadata_file_maintainers(VALUE self)
     {
@@ -105,6 +117,11 @@ namespace
     }
     void do_register_metadata_file()
     {
+        /*
+         * Document-class: Paludis::QA::MetadataFile
+         *
+         * Wrapper around metadata.xml files.
+         */
         c_metadata_file = rb_define_class_under(paludis_qa_module(), "MetadataFile", rb_cObject);
         rb_define_singleton_method(c_metadata_file, "new", RUBY_FUNC_CAST(&metadata_file_new),-1);
         rb_define_method(c_metadata_file, "initialize", RUBY_FUNC_CAST(&metadata_file_init),-1);
diff --git a/ruby/package_database.cc b/ruby/package_database.cc
index beb0b17..7abd7e6 100644
--- a/ruby/package_database.cc
+++ b/ruby/package_database.cc
@@ -32,6 +32,12 @@ namespace
     static VALUE c_package_database;
     static VALUE c_package_database_install_state;
 
+    /*
+     * call-seq:
+     *     favourite_repository -> String
+     *
+     * Fetch the name of our 'favourite' repository
+     */
     VALUE
     package_database_favourite_repository(VALUE self)
     {
@@ -47,6 +53,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     fetch_unique_qualified_package_name(package_name) -> QualifiedPackageName
+     *
+     * Disambiguate a package name
+     */
     VALUE
     package_database_fetch_unique_qualified_package_name(VALUE self, VALUE pkg)
     {
@@ -63,6 +75,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     query(atom, install_state) -> Array
+     *
+     *  Query the repositoty. Returns an array of PackageDatabaseEntry
+     */
     VALUE
     package_database_query(VALUE self, VALUE atom, VALUE state)
     {
@@ -87,6 +105,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     repositories -> Array
+     *
+     *  Returns an array of Repository
+     */
     VALUE
     package_database_repositories(VALUE self)
     {
@@ -108,6 +132,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     fetch_repository(repository_name) -> Repository
+     *
+     *  Fetch a named repository.
+     */
     VALUE
     package_database_fetch_repository(VALUE self, VALUE name)
     {
@@ -124,6 +154,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     better_repository(repository_name_a, repository_name_b) -> String
+     *
+     * Which repository is better?
+     */
     VALUE
     package_database_better_repository(VALUE self, VALUE name1, VALUE name2)
     {
@@ -145,10 +181,14 @@ namespace
 
     void do_register_package_database()
     {
+        /*
+         * Document-class: Paludis::PackageDatabase
+         *
+         * A PackageDatabase can be queried for Package instances.
+         */
         c_package_database = rb_define_class_under(paludis_module(), "PackageDatabase", rb_cObject);
         rb_funcall(c_package_database, rb_intern("private_class_method"), 1, rb_str_new2("new"));
-        rb_define_method(c_package_database, "favourite_repository",
-                RUBY_FUNC_CAST(&package_database_favourite_repository), 0);
+        rb_define_method(c_package_database, "favourite_repository", RUBY_FUNC_CAST(&package_database_favourite_repository), 0);
         rb_define_method(c_package_database, "fetch_unique_qualified_package_name",
                 RUBY_FUNC_CAST(&package_database_fetch_unique_qualified_package_name), 1);
         rb_define_method(c_package_database, "query",
@@ -159,11 +199,17 @@ namespace
                 RUBY_FUNC_CAST(&package_database_fetch_repository), 1);
         rb_define_method(c_package_database, "better_repository",
                 RUBY_FUNC_CAST(&package_database_better_repository), 2);
-
+        /*
+         * Document-module: Paludis::InstallState
+         *
+         * Do we want installed, uninstalled or either when querying?
+         */
         c_package_database_install_state = rb_define_class_under(paludis_module(), "InstallState", rb_cObject);
         for (InstallState l(static_cast<InstallState>(0)), l_end(last_install_state) ; l != l_end ;
                 l = static_cast<InstallState>(static_cast<int>(l) + 1))
             rb_define_const(c_package_database_install_state, value_case_to_RubyCase(stringify(l)).c_str(), INT2FIX(l));
+
+        // cc_enum_special<paludis/package_database.hh, InstallState, c_package_database_install_state>
     }
 }
 
diff --git a/ruby/package_database_entry.cc b/ruby/package_database_entry.cc
index 2e8ee3e..05cf57f 100644
--- a/ruby/package_database_entry.cc
+++ b/ruby/package_database_entry.cc
@@ -59,6 +59,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     version -> VersionSpec
+     *
+     * Fetch VersionSpec.
+     */
     VALUE
     package_database_entry_version(VALUE self)
     {
@@ -74,6 +80,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     version=
+     *
+     * Set package version.
+     */
     VALUE
     package_database_entry_version_set(VALUE self, VALUE version)
     {
@@ -90,6 +102,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     name -> QualifiedPackageName
+     *
+     * Fetch package name
+     */
     VALUE
     package_database_entry_name(VALUE self)
     {
@@ -105,6 +123,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     name=
+     *
+     * Set package name.
+     */
     VALUE
     package_database_entry_name_set(VALUE self, VALUE qpn)
     {
@@ -121,6 +145,22 @@ namespace
         }
     }
 
+    /*
+     * Document-method: repository
+     *
+     * call-seq:
+     *     repository -> String
+     *
+     * Fetch the repository name.
+     */
+    /*
+     * Document-method: repository=
+     *
+     * call-seq:
+     *     repository=
+     *
+     * Set package name.
+     */
     template <typename T_, T_ PackageDatabaseEntry::* m_>
     struct EntryValue
     {
@@ -130,12 +170,12 @@ namespace
             PackageDatabaseEntry * p;
             Data_Get_Struct(self, PackageDatabaseEntry, p);
             return rb_str_new2(stringify(p->*m_).c_str());
-        } 
+        }
 
         static VALUE
         set(VALUE self, VALUE str)
         {
-            try 
+            try
             {
                 PackageDatabaseEntry * p;
                 Data_Get_Struct(self, PackageDatabaseEntry, p);
@@ -146,11 +186,16 @@ namespace
             {
                 exception_to_ruby_exception(e);
             }
-        } 
+        }
     };
-    
+
     void do_register_package_database_entry()
     {
+        /*
+         * Document-class: Paludis::PackageDatabaseEntry
+         *
+         * Holds an entry in a PackageDatabase, and used to identify a specific version of a package in a particular repository.
+         */
         c_package_database_entry = rb_define_class_under(paludis_module(), "PackageDatabaseEntry", rb_cObject);
         rb_define_singleton_method(c_package_database_entry, "new", RUBY_FUNC_CAST(&package_database_entry_new), 3);
         rb_define_method(c_package_database_entry, "initialize", RUBY_FUNC_CAST(&package_database_entry_init), 3);
diff --git a/ruby/paludis_ruby.cc b/ruby/paludis_ruby.cc
index ac184bd..9c76152 100644
--- a/ruby/paludis_ruby.cc
+++ b/ruby/paludis_ruby.cc
@@ -73,6 +73,14 @@ namespace
     static VALUE c_no_such_ebuild_check_type_error;
 #endif
 
+    /* Document-method: match_package
+     *
+     * call-seq:
+     *     match_package (env, atom, target)
+     *
+     * Return whether the specified atom matches the specified target.
+     *
+     */
     VALUE paludis_match_package(VALUE, VALUE en, VALUE a, VALUE t)
     {
         try
@@ -215,6 +223,13 @@ extern "C"
 {
     void Init_Paludis()
     {
+        /*
+         * Document-module: Paludis
+         *
+         * <b>Paludis</b> is the other package mangler, this is the doc to the ruby binding. The C++ library 
+         * documentation[http://paludis.berlios.de/modules.htm] may also help.
+         *
+         */
         c_paludis_module = rb_define_module("Paludis");
         c_environment = rb_define_class_under(paludis_module(), "Environment", rb_cObject);
         c_name_error = rb_define_class_under(c_paludis_module, "NameError", rb_eRuntimeError);
diff --git a/ruby/portage_dep_parser.cc b/ruby/portage_dep_parser.cc
index 725d8d7e..bb1454f 100644
--- a/ruby/portage_dep_parser.cc
+++ b/ruby/portage_dep_parser.cc
@@ -30,6 +30,13 @@ namespace
 {
     static VALUE c_portage_dep_parser;
 
+    /*
+     * call-seq:
+     *     PortageDepParser.parse(dep_string) -> CompositeDepAtom
+     *     PortageDepParser.parse(dep_string, atom_type, permit_any_deps) -> CompositeDepAtom
+     *
+     * Parse a given dependency string, and return an appropriate DepAtom tree.
+     */
     VALUE
     portage_dep_parser_parse(int argc, VALUE * args, VALUE)
     {
@@ -74,6 +81,11 @@ namespace
     {
         rb_require("singleton");
 
+        /*
+         * Document-class: Paludis::PortageDepParser
+         *
+         * The PortageDepParser converts string representations of a dependency specification into a DepAtom instance.
+         */
         c_portage_dep_parser = rb_define_class_under(paludis_module(), "PortageDepParser", rb_cObject);
         rb_funcall(c_portage_dep_parser, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_singleton_method(c_portage_dep_parser, "parse",
diff --git a/ruby/qa_environment.cc b/ruby/qa_environment.cc
index 651ff7e..af83575 100644
--- a/ruby/qa_environment.cc
+++ b/ruby/qa_environment.cc
@@ -38,6 +38,13 @@ namespace
         return self;
     }
 
+    /*
+     * call-seq:
+     *     new(dir)
+     *     new(dir, write_cache_dir)
+     *
+     * Creates a new QAEnvironment
+     */
     VALUE
     qa_environment_new(int argc, VALUE* argv, VALUE self)
     {
@@ -70,6 +77,11 @@ namespace
 
     void do_register_qa_environment()
     {
+        /*
+         * Document-class: Paludis::QA::QAEnvironment
+         *
+         * The QAEnvironment is an environment fo running QA checks in .
+         */
         c_qa_environment = rb_define_class_under(paludis_qa_module(), "QAEnvironment", environment_class());
         rb_define_singleton_method(c_qa_environment, "new", RUBY_FUNC_CAST(&qa_environment_new),-1);
         rb_define_method(c_qa_environment, "initialize", RUBY_FUNC_CAST(&qa_environment_init),-1);
diff --git a/ruby/qualified_package_name.cc b/ruby/qualified_package_name.cc
index 988c3a1..eb7f726 100644
--- a/ruby/qualified_package_name.cc
+++ b/ruby/qualified_package_name.cc
@@ -65,6 +65,38 @@ namespace
         }
     }
 
+    /*
+     * Document-method: category
+     *
+     * call-seq:
+     *     category -> String
+     *
+     * Fetch the category part of the QualifiedPackageName.
+     */
+    /*
+     * Document-method: category=
+     *
+     * call-seq:
+     *     category=
+     *
+     * Set the category.
+     */
+    /*
+     * Document-method: package
+     *
+     * call-seq:
+     *     package -> String
+     *
+     * Fetch the package name part of the QualifiedPackageName.
+     */
+    /*
+     * Document-method: package=
+     *
+     * call-seq:
+     *     package=
+     *
+     * Set the package name.
+     */
     template <typename T_, T_ QualifiedPackageName::* m_>
     struct QPNMember
     {
@@ -110,6 +142,11 @@ namespace
 
     void do_register_qualified_package_name()
     {
+        /*
+         * Document-class: Paludis::QualifiedPackageName
+         *
+         * Represents a category plus package name.
+         */
         c_qualified_package_name = rb_define_class_under(paludis_module(), "QualifiedPackageName", rb_cObject);
         rb_define_singleton_method(c_qualified_package_name, "new", RUBY_FUNC_CAST(&qualified_package_name_new), -1);
         rb_define_method(c_qualified_package_name, "initialize", RUBY_FUNC_CAST(&qualified_package_name_init), -1);
diff --git a/ruby/repository.cc b/ruby/repository.cc
index 24f1e41..49109e4 100644
--- a/ruby/repository.cc
+++ b/ruby/repository.cc
@@ -33,6 +33,12 @@ namespace
     static VALUE c_repository_info;
     static VALUE c_repository_info_section;
 
+    /*
+     * call-seq:
+     *     name
+     *
+     * Returns our name.
+     */
     VALUE
     repository_name(VALUE self)
     {
@@ -48,6 +54,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     has_category_named?(category_name) -> true or false
+     *
+     * Do we have a category with the given name?
+     */
     VALUE
     repository_has_category_named(VALUE self, VALUE cat)
     {
@@ -64,6 +76,16 @@ namespace
     }
 
     VALUE
+
+    //TODO why do we need Document-method here?
+    /*
+     * Document-method: has_package_named?
+     *
+     * call-seq:
+     *     has_package_named?(package_name) -> true or false
+     *
+     * Do we have a package with the given name?
+     */
     repository_has_package_named(VALUE self, VALUE name)
     {
         try
@@ -78,6 +100,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     has_version?(package_name, version) -> true or false
+     *
+     * Do we have a version spec?
+     */
     VALUE
     repository_has_version(VALUE self, VALUE name, VALUE version)
     {
@@ -94,6 +122,12 @@ namespace
         }
     }
 
+    /*
+     *  call-seq:
+     *      category_names -> Array
+     *
+     * Fetch an Array of the names of categories that contain a named package.
+     */
     VALUE
     repository_category_names(VALUE self)
     {
@@ -113,6 +147,12 @@ namespace
         }
     }
 
+    /*
+     *  call-seq:
+     *      category_names_containing_package(package) -> Array
+     *
+     * Fetch an Array of the categories containing the named package.
+     */
     VALUE
     repository_category_names_containing_package(VALUE self, VALUE pkg)
     {
@@ -134,6 +174,12 @@ namespace
         }
     }
 
+    /*
+     *  call-seq:
+     *      package_names(category) -> Array
+     *
+     * Fetch an Array of the packages with a named category.
+     */
     VALUE
     repository_package_names(VALUE self, VALUE cat)
     {
@@ -155,6 +201,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     version_specs(qualified_package_name) -> Array
+     *
+     * Fetch our versions.
+     */
     VALUE
     repository_version_specs(VALUE self, VALUE qpn)
     {
@@ -176,6 +228,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     version_metadata(qualified_package_name, version_spec) -> VersionMetadata
+     *
+     * Fetch metadata.
+     */
     VALUE
     repository_version_metadata(VALUE self, VALUE name, VALUE version)
     {
@@ -192,6 +250,102 @@ namespace
         }
     }
 
+    /*
+     * Document-method: installable_interface
+     *
+     * call-seq:
+     *     installable_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: installed_interface
+     *
+     * call-seq:
+     *     installed_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: mask_interface
+     *
+     * call-seq:
+     *     mask_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: news_interface
+     *
+     * call-seq:
+     *     news_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: sets_interface
+     *
+     * call-seq:
+     *     sets_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: uninstallable_interface
+     *
+     * call-seq:
+     *     uninstallable_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: use_interface
+     *
+     * call-seq:
+     *     use_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: world_interface
+     *
+     * call-seq:
+     *     world_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: mirrors_interface
+     *
+     * call-seq:
+     *     mirrors_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: environment_variable_interface
+     *
+     * call-seq:
+     *     environment_variable_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: provides_interface
+     *
+     * call-seq:
+     *     provides_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
+    /*
+     * Document-method: virtuals_interface
+     *
+     * call-seq:
+     *     virtuals_interface -> self or Nil
+     *
+     * Returns self if the repository supports the interface, otherwise Nil.
+     */
     template <typename T_, T_ * RepositoryCapabilities::* m_>
     struct Interface
     {
@@ -203,6 +357,12 @@ namespace
         }
     };
 
+    /*
+     * call-seq:
+     *      repository_info(verbose) -> RepositoryInfo
+     *
+     * Fetch our RepositoryInfo
+     */
     VALUE
     repository_info(VALUE self, VALUE verbose)
     {
@@ -213,6 +373,12 @@ namespace
         return Data_Wrap_Struct(c_repository_info, 0, &Common<RepositoryInfo::ConstPointer>::free, p);
     }
 
+    /*
+     * call-seq:
+     *     info_sections -> Array
+     *
+     * Fetch an array of our sections.
+     */
     VALUE
     repository_info_sections(VALUE self)
     {
@@ -235,7 +401,12 @@ namespace
             exception_to_ruby_exception(e);
         }
     }
-
+    /*
+     * call-seq:
+     *     kvs -> Hash
+     *
+     * Returns the key/value pairs within the section.
+     */
     VALUE
     repository_info_section_kvs(VALUE self)
     {
@@ -256,6 +427,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     header -> String
+     *
+     * Our heading
+     */
     VALUE
     repository_info_section_header(VALUE self)
     {
@@ -264,6 +441,12 @@ namespace
         return rb_str_new2((*self_ptr)->heading().c_str());
     }
 
+    /*
+     * call-seq:
+     *     contents(qualified_package_name, version_spec) -> Array or Nil
+     *
+     * Fetches the package contents, if the Repository includes the installed_interface
+     */
     VALUE
     repository_contents(VALUE self, VALUE qpn, VALUE vs)
     {
@@ -292,6 +475,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     installed_time(qualified_package_name, version_spec) -> Array or Nil
+     *
+     * Fetches the package install time, if the Repository includes the installed_interface
+     */
     VALUE
     repository_installed_time(VALUE self, VALUE qpn, VALUE vs)
     {
@@ -320,6 +509,11 @@ namespace
 
     void do_register_repository()
     {
+        /*
+         * Document-class: Paludis::Repository
+         *
+         * A Repository provides a representation of a physical repository to a PackageDatabase.
+         */
         c_repository = rb_define_class_under(paludis_module(), "Repository", rb_cObject);
         rb_funcall(c_repository, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_repository, "name", RUBY_FUNC_CAST(&repository_name), 0);
@@ -367,10 +561,20 @@ namespace
         rb_define_method(c_repository, "contents", RUBY_FUNC_CAST(&repository_contents), 2);
         rb_define_method(c_repository, "installed_time", RUBY_FUNC_CAST(&repository_installed_time), 2);
 
+        /*
+         * Document-class: Paludis::RepositoryInfo
+         *
+         * Information about a Repository, for the end user.
+         */
         c_repository_info = rb_define_class_under(paludis_module(), "RepositoryInfo", rb_cObject);
         rb_funcall(c_repository_info, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_repository_info, "sections", RUBY_FUNC_CAST(&repository_info_sections), 0);
 
+        /*
+         * Document-class: Paludis::RepositoryInfoSection
+         *
+         * A section of information about a Repository.
+         */
         c_repository_info_section = rb_define_class_under(paludis_module(), "RepositoryInfoSection", rb_cObject);
         rb_funcall(c_repository_info_section, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_repository_info_section, "kvs", RUBY_FUNC_CAST(&repository_info_section_kvs), 0);
diff --git a/ruby/version_metadata.cc b/ruby/version_metadata.cc
index 27596fb..751c5ef 100644
--- a/ruby/version_metadata.cc
+++ b/ruby/version_metadata.cc
@@ -40,26 +40,56 @@ namespace
         return ((**self_ptr).*m)() ? self : Qnil;
     }
 
+    /*
+     * call-seq:
+     *     get_ebuild_interface -> self or Nil
+     *
+     * Returns self if the VersionMetadata supports the interface, otherwise Nil.
+     */
     VALUE version_metadata_get_ebuild_interface(VALUE self)
     {
         return version_metadata_get_interface(self, &VersionMetadata::get_ebuild_interface);
     }
 
+    /*
+     * call-seq:
+     *     get_ebin_interface -> self or Nil
+     *
+     * Returns self if the VersionMetadata supports the interface, otherwise Nil.
+     */
     VALUE version_metadata_get_ebin_interface(VALUE self)
     {
         return version_metadata_get_interface(self, &VersionMetadata::get_ebin_interface);
     }
 
+    /*
+     * call-seq:
+     *     get_cran_interface -> self or Nil
+     *
+     * Returns self if the VersionMetadata supports the interface, otherwise Nil.
+     */
     VALUE version_metadata_get_cran_interface(VALUE self)
     {
         return version_metadata_get_interface(self, &VersionMetadata::get_cran_interface);
     }
 
+    /*
+     * call-seq:
+     *     get_virtual_interface -> self or Nil
+     *
+     * Returns self if the VersionMetadata supports the interface, otherwise Nil.
+     */
     VALUE version_metadata_get_virtual_interface(VALUE self)
     {
         return version_metadata_get_interface(self, &VersionMetadata::get_virtual_interface);
     }
 
+    /*
+     * call-seq:
+     *     license
+     *
+     * Fetch our license, as a DepAtom structure.
+     */
     VALUE
     version_metadata_license(VALUE self)
     {
@@ -68,6 +98,46 @@ namespace
         return dep_atom_to_value((*self_ptr)->license());
     }
 
+    /*
+     * Document-method: slot
+     *
+     * call-seq:
+     *     slot
+     *
+     * Our slot
+     */
+    /*
+     * Document-method: license_string
+     *
+     * call-seq:
+     *     license_string
+     *
+     * Our license as a String
+     */
+    /*
+     * Document-method: eapi
+     *
+     * call-seq:
+     *     eapi
+     *
+     * Our eapi
+     */
+    /*
+     * Document-method: homepage
+     *
+     * call-seq:
+     *     homepage
+     *
+     * Our homepage
+     */
+    /*
+     * Document-method: description
+     *
+     * call-seq:
+     *     description
+     *
+     * Our description
+     */
     template <typename T_, T_ VersionMetadataBase::* m_>
     struct BaseValue
     {
@@ -80,6 +150,62 @@ namespace
         }
     };
 
+    /*
+     * Document-method: provide_string
+     *
+     * call-seq:
+     *     provide_string
+     *
+     * Fetches the package provide_string, if get_ebuild_interface is not Nil.
+     */
+    /*
+     * Document-method: src_uri
+     *
+     * call-seq:
+     *     src_uri
+     *
+     * Fetches the package src_uri, if get_ebuild_interface is not Nil.
+     */
+    /*
+     * Document-method: restrict_string
+     *
+     * call-seq:
+     *     restrict_string
+     *
+     * Fetches the package restrict_string, if get_ebuild_interface is not Nil.
+     */
+    /*
+     * Document-method: keywords
+     *
+     * call-seq:
+     *     keywords
+     *
+     * Fetches the package keywords, if get_ebuild_interface is not Nil.
+     */
+    /*
+     * Document-method: eclass_keywords
+     *
+     * call-seq:
+     *     eclass_keywords
+     *
+     * Fetches the package eclass_keywords, if get_ebuild_interface is not Nil.
+     */
+    /*
+     * Document-method: iuse
+     *
+     * call-seq:
+     *     iuse
+     *
+     * Fetches the package iuse, if get_ebuild_interface is not Nil.
+     */
+    /*
+     * Document-method: inherited
+     *
+     * call-seq:
+     *     inherited
+     *
+     * Fetches the package inherited, if get_ebuild_interface is not Nil.
+     */
     template <typename T_, T_ EbuildVersionMetadata::* m_>
     struct EbuildValue
     {
@@ -95,6 +221,30 @@ namespace
         }
     };
 
+    /*
+     * Document-method: build_depend
+     *
+     * call-seq:
+     *     build_depend -> DepAtom
+     *
+     * Fetches build_depend information as a DepAtom
+     */
+    /*
+     * Document-method: run_depend
+     *
+     * call-seq:
+     *     run_depend -> DepAtom
+     *
+     * Fetches run_depend information as a DepAtom
+     */
+    /*
+     * Document-method: post_depend
+     *
+     * call-seq:
+     *     post_depend -> DepAtom
+     *
+     * Fetches post_depend information as a DepAtom
+     */
     template <DepAtom::ConstPointer (VersionMetadataDeps::* m_) () const>
     struct DependValue
     {
@@ -108,6 +258,30 @@ namespace
         }
     };
 
+    /*
+     * Document-method: build_depend_string
+     *
+     * call-seq:
+     *     build_depend_string -> String
+     *
+     * Fetches build_depend information as a String
+     */
+    /*
+     * Document-method: run_depend_string
+     *
+     * call-seq:
+     *     run_depend_string -> String
+     *
+     * Fetches run_depend information as a String
+     */
+    /*
+     * Document-method: post_depend_string
+     *
+     * call-seq:
+     *     post_depend_string -> String
+     *
+     * Fetches post_depend information as a String
+     */
     template <std::string VersionMetadataDeps::* m_>
     struct DependValueString
     {
@@ -119,7 +293,14 @@ namespace
             return rb_str_new2(((&(*self_ptr)->deps)->*m_).c_str());
         }
     };
-
+    /*
+     * Document-method: origin_source
+     *
+     * call-seq:
+     *     origin_source -> PackageDatabaseEntry
+     *
+     * Returnd the PackageDatabaseEntry from which the package was installed.
+     */
     template <CountedPtr<PackageDatabaseEntry, count_policy::ExternalCountTag> VersionMetadataOrigins::* m_>
     struct VMOrigins
     {
@@ -141,6 +322,11 @@ namespace
 
     void do_register_version_metadata()
     {
+        /*
+         * Document-class: Paludis::VersionMetadata
+         *
+         * Metadata about a package version.
+         */
         c_version_metadata = rb_define_class_under(paludis_module(), "VersionMetadata", rb_cObject);
         rb_funcall(c_version_metadata, rb_intern("private_class_method"), 1, rb_str_new2("new"));
         rb_define_method(c_version_metadata, "get_ebuild_interface", RUBY_FUNC_CAST(&version_metadata_get_ebuild_interface), 0);
diff --git a/ruby/version_spec.cc b/ruby/version_spec.cc
index f0ee77b..b233f46 100644
--- a/ruby/version_spec.cc
+++ b/ruby/version_spec.cc
@@ -54,6 +54,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     remove_revision -> VersionSpec
+     *
+     * Returns a VersionSpec without the revision part.
+     */
     VALUE
     version_spec_remove_revision(VALUE self)
     {
@@ -67,6 +73,12 @@ namespace
         }
     }
 
+    /*
+     * call-seq:
+     *     revision_only -> String
+     *
+     * Revision part only (or "r0").
+     */
     VALUE
     version_spec_revision_only(VALUE self)
     {
@@ -82,6 +94,12 @@ namespace
 
     void do_register_version_spec()
     {
+        /*
+         * Document-class: Paludis::VersionSpec
+         *
+         * A VersionSpec represents a version number (for example, 1.2.3b-r1).
+         *
+         */
         c_version_spec = rb_define_class_under(paludis_module(), "VersionSpec", rb_cObject);
         rb_define_singleton_method(c_version_spec, "new", RUBY_FUNC_CAST(&version_spec_new), 1);
         rb_define_method(c_version_spec, "initialize", RUBY_FUNC_CAST(&version_spec_init), 1);