[Hiki] update - Naming and Conversion Rules (ruby-gnome2-doc-cvs) - Ruby-GNOME2

-------------------------
REMOTE_ADDR = 61.204.181.66
REMOTE_HOST = 
-------------------------
= Ruby-GNOME2 naming/conversion rules
Implementing Ruby-GNOME components, you should conform to this document. But this has never been complete yet. If you have any suggestion, mail to Ruby-GNOME2 Mailing list.

== Library names
Ruby-GNOME2 means whole of the project.

If you say a part of Ruby-GNOME2, use "/".

* Ruby/GNOME - gnome2 module
* Ruby/GnomeCanvas - gnomecanvas2 module
* Ruby/GTK - gtk2 module
* Ruby/GLib - glib2 module (glib2 is always required other libraries)
* Ruby/Libglade - libglade 

You also can say as Ruby/GNOME2, Ruby/GTK2.
This is used when you restrict it against Ruby-GNOME(GTK+1.2based).
Accessors(Setter/Getter methods)

There are two patterns. In each patterns, you should implement all methods.

* Method has An argument

 setter: hoge=(a)             #return a.
         set_hoge(a)          #return self.
 getter: hoge                 #return hoge's value.

* Method has more than 2 arguments

 setter: set_fuga(a, b)       #return self.
 getter: fuga                 #Have no arguments. return fuga's value.
         get_fuga(a, b)       #Have arguments. return fuga's value.

== is_* methods
Convert is_foo -> foo?. Because it is more natural in Ruby.

== has_*, use_* methods
If the method return gboolean, add '?' to the end of the word.

  has_foo -> has_foo?
  use_bar -> use_foo?

== set/get_has_*, set/get_use_* methods

  get_has_foo -> has_foo?
  set_has_foo -> has_foo=(a), set_has_foo(a)
  get_use_foo -> use_foo?
  set_use_foo -> use_foo=(a), set_use_foo(a)

== classname_foo_set_bar, classname_foo_get_bar ...
There are some methods which don't start verb like set/get/is/has/use. We think these pattern is not good naming. But we don't convert(remove verbs) like as follows.

  gtk_classname_foo_set_bar -> Gtk::ClassName#foo_set_bar
  gtk_classname_foo_get_bar -> Gtk::ClassName#foo_get_bar
  gtk_classname_foo_get_bar -> Gtk::ClassName#foo_get_bar?
  gtk_classname_foo_is_bar -> Gtk::ClassName#foo_is_bar?
  gtk_classname_foo_has_bar -> Gtk::ClassName#foo_has_bar?
  gtk_classname_foo_use_bar -> Gtk::ClassName#foo_use_bar?

== Instance methods which return void
Return self.

== initialize
Return Qnil.

== Class methods/Module methods which return void
Return Qnil.

== Destructive methods(which changes the object itself)
Usually destructive methods add "!" to the end of the words. For example, Gtk::TreeIter#first, #next!, Gtk::TreePath#prev!, #next!, #up!, #down!.

(*) Strictly, '!' doesn't express not destructive but "careful or more dangerous"

== *_foreach methods
Convert it to 'each'.

== The methods which return boolean variable
Add '?' to end of method. ex) foo -> foo?.
But some methods which don't aim to get return value, you should not add '?'.

  do_something -> do_something  #Do something, as result, return gboolean.
  some_status -> some_status?   #Get statuses or properties.

== Constants
Sometimes this definition is difficult. When you confuse how to implement about constants, you should ask it to ML.

* Abolish Constants module. e.g. Gtk::ItemFactory::Constants.
* If the constants belong an object(class or module) obiviouly, include the constants among members of the object.

   e.g.)In the case of GtkDialog
      GtkDialogFlags
         GTK_DIALOG_MODAL               -> Gtk::Dialog::MODAL
         GTK_DIALOG_DESTROY_WITH_PARENT -> Gtk::Dialog::DESTROY_WITH_PARENT
         GTK_DIALOG_NO_SEPARATOR        -> Gtk::Dialog::NO_SEPARATOR

      GtkResponseType
         GTK_RESPONSE_NONE     ->  Gtk::Dialog::RESPONSE_NONE
         GTK_RESPONSE_REJECT   ->  Gtk::Dialog::RESPONSE_REJECT
         GTK_RESPONSE_ACCEPT   ->  Gtk::Dialog::RESPONSE_ACCEPT

* The constants is independant from objects(Almost in 'Standard Enumerations').

    GTK_FOO_BAR -> Gtk::FOO_BAR

== Classes, Modules and Methods
Usually a C Struct is mapping a ruby class. But if there are no C Struct, you may implement the group as module.

By way of exception, some methods that first argument is other class's instance may be better to implement to other class.

== Plural methods which are same meaning but arguments are different
Combine them in a method.

== Miscellaneous
* Add new method which does not exist in C library but you want.
* Change C library's function name more naturally as method name of Ruby. 

They are not forbidden in Ruby-GNOME2. Because Ruby-GNOME2 is not just only wrapper for GNOME/GTK+. But they are not recommanded way, so it is better to ask ML about it. 

- ((<Masao>))
-------------------------
= Ruby-GNOME2 naming/conversion rules
Implementing Ruby-GNOME components, you should conform to this document. But this has never been complete yet. If you have any suggestion, mail to Ruby-GNOME2 Mailing list.