Made autodoc ignore numinputs=0.

Added more typemap(doc) for documenting STL
and standard ruby methods.
Added missing RUBY_SELF typemap.



git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@9754 626c5289-ae23-0410-ae9c-e8d60b6d4f22

CHANGES.current

@@ -1,6 +1,22 @@
 Version 1.3.32 (in progress)
 ============================
 
+05/03/2007: gga
+	    [Ruby]
+	    Changed flag -feature to be -init_name to better reflect its
+	    purpose and avoid confusion with -features.
+
+05/03/2007: gga
+	    [Ruby]
+	    Improved autodoc generation.
+	    Added autodoc .swg files to Ruby library for easily adding 
+	    documentation to common Ruby methods and STL methods.
+	    Made test suite always generate autodocs.
+
+05/03/2007: gga
+	    [Ruby]
+	    Removed some warnings from STL and test suite.
+
 05/02/2007: mgossage
             [Lua] Fixed issues with C++ classes and hierachies across multiple
 	    source files. Fixed imports test case & added run test.

Examples/test-suite/li_std_stream.i

@@ -1,5 +1,4 @@
 %module li_std_stream
-%feature("autodoc","4");
 
 %inline %{
   struct A;  

Examples/test-suite/ruby/Makefile.in

@@ -43,16 +43,19 @@ SWIGOPT += -noautorename
 naming.cpptest: SWIGOPT = -autorename
 
 %.cpptest: 
+	SWIGOPT = -features autodoc=4
 	$(setup) \
 	($(swig_and_compile_cpp); ) &&\
 	$(run_testcase)
 
 %.ctest:
+	SWIGOPT = -features autodoc=4
 	$(setup) \
 	($(swig_and_compile_c); ) &&\
 	$(run_testcase)
 
 %.multicpptest: 
+	SWIGOPT = -features autodoc=4
 	$(setup) \
 	($(swig_and_compile_multi_cpp); ) &&\
 	$(run_testcase)

Lib/ruby/rubyautodoc.swg

@@ -14,11 +14,66 @@
 %enddef
 
 
-AUTODOC(to_a, "Convert class to an Array");
+AUTODOC(to_i, "Convert $class to an Integer");
+AUTODOC(to_f, "Convert $class to a Float");
+AUTODOC(coerce, "Coerce class to a number");
+AUTODOC(to_a, "Convert $class to an Array");
 AUTODOC(to_s, "Convert class to a String representation");
 AUTODOC(inspect, "Inspect class and its contents");
+
+AUTODOC(at, "Return element at a certain index");
 AUTODOC(__getitem__, "Element accessor/slicing");
 AUTODOC(__setitem__, "Element setter/slicing");
+AUTODOC(slice, "Return a slice (portion of) the $class");
+
+AUTODOC(push, "Add an element at the end of the $class");
+AUTODOC(pop, "Remove and return element at the end of the $class");
+AUTODOC(shift, "Remove and return element at the beginning of the $class");
+AUTODOC(unshift, "Add one or more elements at the beginning of the $class");
+AUTODOC(first, "Return the first element in $class");
+AUTODOC(last, "Return the last element in $class");
+
+
+//
+// Common Object methods
+//
+AUTODOC(hash, "Hashing function for class");
+AUTODOC(dup, "Create a duplicate of the class and unfreeze it if needed");
+AUTODOC(clone, "Create a duplicate of the class");
+
+//
+// Container methods
+//
+AUTODOC(empty, "Check if $class is empty");
+AUTODOC(size, "Size or Length of the $class");
+AUTODOC(insert, "Insert one or more new elements in the $class");
+
+//
+// Iterator methods (block)
+//
+AUTODOC(each, "Iterate thru each element in the $class.  A block must be provided");
+AUTODOC(find, "Find an element in the class");
+AUTODOC(each_key, "Iterate thru each key element in the $class.  A block must be provided");
+AUTODOC(each_value, "Iterate thru each key element in the $class.  A block must be provided");
+AUTODOC(reject, "Iterate thru each element in the $class and reject those that fail a condition returning a new $class.  A block must be provided");
+AUTODOC(reject_bang, "Iterate thru each element in the $class and reject those that fail a condition.  A block must be provided.  $class is modified in place");
+AUTODOC(select, "Iterate thru each element in the $class and select those that match a condition.  A block must be provided");
+AUTODOC(delete_at, "Delete an element at a certain index");
+AUTODOC(__delete__, "Delete an element at a certain index");
+
+
+//
+// Hash methods
+//
+AUTODOC(keys, "Return an Array of key elements");
+AUTODOC(values, "Return an Array of value elements");
+AUTODOC(values_at, "Return an Array of value elements matching the conditions");
+
+
+//
+// Operators
+//
+#ifdef __cplusplus
 AUTODOC(operator==, "Equality comparison operator");
 AUTODOC(operator<=, "Lower or equal comparison operator");
 AUTODOC(operator>=, "Higher or equal comparison operator");
@@ -34,21 +89,22 @@ AUTODOC(operator&, "AND operator");
 AUTODOC(operator|, "OR operator");
 AUTODOC(operator^, "XOR operator");
 AUTODOC(operator~, "Invert operator");
+#endif
+AUTODOC(__eq__, "Equality comparison operator");
+AUTODOC(__le__, "Lower or equal comparison operator");
+AUTODOC(__ge__, "Higher or equal comparison operator");
+AUTODOC(__lt__, "Lower than comparison operator");
+AUTODOC(__gt__, "Higher than comparison operator");
+AUTODOC(__lshift__, "Left shifting or appending operator");
+AUTODOC(__rshift__, "Right shifting operator or extracting operator");
+AUTODOC(__add___, "Add operator");
+AUTODOC(__sub__, "Substraction operator");
+AUTODOC(__pos__, "Positive operator");
+AUTODOC(__neg__, "Negation operator");
+AUTODOC(__and__, "AND operator");
+AUTODOC(__or__, "OR operator");
+AUTODOC(__xor__, "XOR operator");
+AUTODOC(__negate__, "Invert operator");
 AUTODOC(__pow__, "Exponential operator");
 AUTODOC(__divmod__, "Modulo of division");
-AUTODOC(hash, "Hashing function for class");
-AUTODOC(dup, "Create a duplicate of the class and unfreeze it if needed");
-AUTODOC(clone, "Create a duplicate of the class");
-AUTODOC(coerce, "Coerce class to a number");
-AUTODOC(__cmp__, "Comparison operator");
-AUTODOC(size, "Size or Length of the container");
-AUTODOC(slice, "Return a slice (portion of) the container");
-AUTODOC(each, "Iterate thru each element in the container.  A block must be provided");
-AUTODOC(find, "Find an element in the class or container");
-AUTODOC(each_key, "Iterate thru each key element in the container.  A block must be provided");
-AUTODOC(each_value, "Iterate thru each key element in the container.  A block must be provided");
-AUTODOC(reject, "Iterate thru each element in the container and reject those that fail a condition returning a new container.  A block must be provided");
-AUTODOC(reject_bang, "Iterate thru each element in the container and reject those that fail a condition.  A block must be provided.  Container is modified in place");
-AUTODOC(select, "Iterate thru each element in the container and select those that match a condition.  A block must be provided");
-
-
+AUTODOC(__cmp__, "Comparison operator.  Returns < 0 for less than, 0 for equal or > 1 for higher than.");

Lib/ruby/rubycontainer.swg

@@ -485,11 +485,11 @@ namespace swig
 
   %fragment("RubySequence_Cont");
 
-  %newobject iterator(VALUE *RUBY_SELF);
+  %newobject iterator;
   %extend  {
-    swig::RubySwigIterator* iterator(VALUE *RUBY_SELF) {
-      return swig::make_output_iterator(self->begin(), self->begin(), 
-					self->end(), *RUBY_SELF);
+    swig::RubySwigIterator* iterator(VALUE* RUBY_SELF) {
+      return swig::make_output_iterator($self->begin(), $self->begin(), 
+					$self->end(), *RUBY_SELF);
     }
   }
 #endif //SWIG_EXPORT_ITERATOR_METHODS

Lib/ruby/rubystdautodoc.swg

@@ -12,17 +12,25 @@
 // For STL autodocumentation
 //
 AUTODOC(c_str, "Convert class to a String representation");
-AUTODOC(begin, "Return an iterator to the beginning of the container");
-AUTODOC(end, "Return an iterator to past the end of the container");
-AUTODOC(rbegin, "Return a reverse iterator to the beginning (the end) of the container");
-AUTODOC(rend, "Return a reverse iterator to past the end (past the beginning) of the container");
-AUTODOC(length, "Size or Length of the container");
-AUTODOC(resize, "Resize the size of the container");
-AUTODOC(capacity, "Reserved capacity of the container");
-AUTODOC(reserve, "Reserve memory in the container for a number of elements");
-AUTODOC(erase, "Delete a portion of the container");
-AUTODOC(max_size, "Maximum size of elements allowed in the container");
-AUTODOC(iterator, "Return an iterator to the container");
-AUTODOC(empty, "Check if the container is empty or not");
-AUTODOC(rfind, "Find an element in reverse usually starting from the end of the container");
-AUTODOC(substr, "Return a portion of the String");
+AUTODOC(begin, "Return an iterator to the beginning of the $class");
+AUTODOC(end, "Return an iterator to past the end of the $class");
+AUTODOC(rbegin, "Return a reverse iterator to the beginning (the end) of the $class");
+AUTODOC(rend, "Return a reverse iterator to past the end (past the beginning) of the $class");
+AUTODOC(length, "Size or Length of the $class");
+AUTODOC(replace, "Replace all or a portion of the $class");
+AUTODOC(resize, "Resize the size of the $class");
+AUTODOC(capacity, "Reserved capacity of the $class");
+AUTODOC(reserve, "Reserve memory in the $class for a number of elements");
+AUTODOC(erase, "Delete a portion of the $class");
+AUTODOC(max_size, "Maximum size of elements allowed in the $class");
+AUTODOC(iterator, "Return an iterator to the $class");
+AUTODOC(empty, "Check if the $class is empty or not");
+AUTODOC(rfind, "Find an element in reverse usually starting from the end of the $class");
+AUTODOC(assign, "Assign a new $class or portion of it");
+AUTODOC(front, "Return the first element in $class");
+AUTODOC(back, "Return the last element in $class");
+AUTODOC(second, "Return the second element in $class");
+AUTODOC(push_front, "Add an element at the beginning of the $class");
+AUTODOC(push_back, "Add an element at the end of the $class");
+AUTODOC(pop_front, "Remove and return element at the beginning of the $class");
+AUTODOC(pop_back, "Remove and return an element at the end of the $class");

Lib/ruby/rubytypemaps.swg

@@ -50,6 +50,13 @@
 /* raise */
 #define SWIG_Raise(obj, type, desc)      rb_exc_raise(SWIG_Ruby_ExceptionType(desc, obj)) 
 
+/* Get the address of the 'Ruby self' object */
+
+%typemap(in,numinputs=0,noblock=1) VALUE* RUBY_SELF {
+  $1 = &self;
+}
+
+
 /* Include the unified typemap library */
 %include <typemaps/swigtypemaps.swg>
 

Lib/ruby/std_ios.i

@@ -3,4 +3,12 @@
 
 %rename(ios_base_in) std::ios_base::in;
 
+AUTODOC(cerr, "Standard C++ error stream");
+AUTODOC(cout, "Standard C++ output stream");
+AUTODOC(cin,  "Standard C++ input stream");
+AUTODOC(clog, "Standard C++ logging stream");
+AUTODOC(endl,  "Add an end line to stream");
+AUTODOC(ends,  "Ends stream");
+AUTODOC(flush, "Flush stream");
+
 %include <std/std_ios.i>

Lib/ruby/std_map.i

@@ -313,12 +313,12 @@
 
     %newobject key_iterator(VALUE *RUBY_SELF);
     swig::RubySwigIterator* key_iterator(VALUE *RUBY_SELF) {
-      return swig::make_output_key_iterator(self->begin(), self->begin(), self->end(), *RUBY_SELF);
+      return swig::make_output_key_iterator($self->begin(), $self->begin(), $self->end(), *RUBY_SELF);
     }
 
     %newobject value_iterator(VALUE *RUBY_SELF);
     swig::RubySwigIterator* value_iterator(VALUE *RUBY_SELF) {
-      return swig::make_output_value_iterator(self->begin(), self->begin(), self->end(), *RUBY_SELF);
+      return swig::make_output_value_iterator($self->begin(), $self->begin(), $self->end(), *RUBY_SELF);
     }
 
   }

Lib/ruby/std_string.i

@@ -3,6 +3,8 @@
 %warnfilter(378) std::basic_string::operator!=;
 
 
+AUTODOC(substr, "Return a portion of the String");
+
 %rename("empty?") std::string::empty;
 %rename("empty?") std::basic_string::empty;
 

Source/Modules/ruby.cxx

@@ -132,7 +132,7 @@ Ruby Options (available with -ruby)\n\
      -autorename     - Enable renaming of classes and methods to follow Ruby coding standards\n\
      -noautorename   - Disable renaming of classes and methods (default)\n\
      -prefix <name>  - Set a prefix <name> to be prepended to all names\n\
-     -feature <name> - Set feature name to <name> (used by `require')\n";
+     -init_name <name> - Set entry function to Init_<name> (used by `require')\n";
 
 
 #define RCLASS(hash, name) (RClass*)(Getattr(hash, name) ? Data(Getattr(hash, name)) : 0)
@@ -331,6 +331,7 @@ private:
       type = type ? type : Getattr(p, "type");
       value = value ? value : Getattr(p, "value");
 
+
       String *tm = Getattr(p, "tmap:in");
       if (tm) {
 	pnext = Getattr(p, "tmap:in:next");
@@ -338,10 +339,17 @@ private:
 	pnext = nextSibling(p);
       }
 
+      // Skip ignored input attributes
+      if (checkAttribute(p, "tmap:in:numinputs", "0"))
+	continue;
+
       // Skip the 'self' parameter which in ruby is implicit
       if ( Cmp(name, "self") == 0 )
 	continue;
 
+      // Make __p parameters just p (as used in STL)
+      Replace( name, "__", "", DOH_REPLACE_FIRST );
+
       if (Len(doc)) {
 	// add a comma to the previous one if any
 	Append(doc, ", ");
@@ -620,6 +628,7 @@ private:
 	break;
       case STRING_AUTODOC:
 	extended = 2;
+	Replaceall( autodoc, "$class", class_name );
 	Printv(doc, autodoc, ".", NIL);
 	break;
       case EXTEND_AUTODOC:
@@ -697,7 +706,7 @@ public:
     /* Look for certain command line options */
     for (int i = 1; i < argc; i++) {
       if (argv[i]) {
-	if (strcmp(argv[i], "-feature") == 0) {
+	if (strcmp(argv[i], "-init_name") == 0) {
 	  if (argv[i + 1]) {
 	    char *name = argv[i + 1];
 	    feature = NewString(name);