add RDoc documentation

This should help developers find their way in case they
are offline and unable to access the (unmaintained) website.

3 files changed, 209 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..63dfd4f
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,8 @@
+*.gem
+*.log
+*.o
+*.so
+Makefile
+/doc
+/.ri
+mahoro.txt
diff --git a/doc.mk b/doc.mk
new file mode 100644
index 0000000..9d9af9b
--- /dev/null
+++ b/doc.mk
@@ -0,0 +1,26 @@
+all::
+
+.ri/created.rid: mahoro.c
+        rdoc --ri -o $(@D) $<
+
+order =
+order += Mahoro
+order += Mahoro.new
+order += Mahoro\#file
+order += Mahoro\#buffer
+order += Mahoro\#flags=
+order += Mahoro\#valid?
+order += Mahoro\#compile
+order += Mahoro.compile
+
+mahoro.txt: .ri/created.rid
+        ( \
+                for i in $(order); \
+                do \
+                        ri --no-standard-docs -T -d .ri -w 80 "$$i" \
+                                | col -b \
+                                | grep -vF $(CURDIR)/.ri; \
+                done \
+        ) > $@
+
+all:: mahoro.txt
diff --git a/mahoro.c b/mahoro.c
index 689ca0e..fe02cf6 100644
--- a/mahoro.c
+++ b/mahoro.c
@@ -1,5 +1,9 @@
 /*
  * This file is Public Domain.
+ *
+ * Note: The current maintainer (Eric Wong) respects and preserves the
+ * original coding style of the original author (Shu-yu Guo) in case
+ * he ever chooses to return to this project.
  */
 
 #include <ruby.h>
@@ -15,6 +19,7 @@
 static VALUE cMahoro;
 static VALUE eMahoroError;
 
+/* :nodoc: called automatically by GC */
 static void
 mahoro_free(ptr)
         void *ptr;
@@ -23,6 +28,7 @@ mahoro_free(ptr)
                 magic_close((magic_t)ptr);
 }
 
+/* :nodoc: called automatically on Mahoro#initialize */
 static VALUE
 mahoro_allocate(klass)
         VALUE klass;
@@ -30,6 +36,20 @@ mahoro_allocate(klass)
         return Data_Wrap_Struct(klass, 0, mahoro_free, 0);
 }
 
+/*
+ * call-seq:
+ *        Mahoro.new(flags = Mahoro::NONE, path = nil)        ->        mahoro_obj
+ *
+ * Create and initialize a new Mahoro object.
+ * +flags+ may be one or more of any combination of the Mahoro:: constants
+ * supported by Mahoro#flags=.
+ * +path+ (if not nil) is a colon-separated list of database files, see
+ * Mahoro#load.
+ *
+ * If +path+ is not given (or nil), the default database is used.
+ * Consult your libmagic(3) documentation for the location of that file
+ * as it varies by installation.
+ */
 static VALUE
 mahoro_initialize(argc, argv, self)
         int argc;
@@ -65,6 +85,15 @@ mahoro_initialize(argc, argv, self)
         return self;
 }
 
+/*
+ * call-seq:
+ *        mahoro_obj.file(filename)        ->        String
+ *
+ * Returns a textual description of the contents of the +filename+ given.
+ * Use Mahoro#buffer instead of this method if the contents of your
+ * file is already in memory.
+ * Raises Mahoro::Error on failed lookups.
+ */
 static VALUE
 mahoro_file(self, path)
         VALUE self, path;
@@ -79,6 +108,16 @@ mahoro_file(self, path)
         return rb_str_new2(msg);
 }
 
+/*
+ * call-seq:
+ *        mahoro_obj.buffer(buffer)        ->        String
+ *
+ * Returns a textual description of the contents of the +buffer+ given.
+ * +buffer+ should be a String object.
+ * Use Mahoro#file instead of this method if the contents is not already
+ * in memory (and possibly too large to fit into memory).
+ * Raises Mahoro::Error on failed lookups.
+ */
 static VALUE
 mahoro_buffer(self, input)
         VALUE self, input;
@@ -96,6 +135,39 @@ mahoro_buffer(self, input)
         return rb_str_new2(msg);
 }
 
+/*
+ * call-seq:
+ *        mahoro_obj.flags = flags
+ *
+ * Change the behavior of an already-initialized Mahoro object.  The
+ * behavior of a Mahoro object is specified at load time, but may be
+ * changed after-the-fact.
+ * +flags+ is a bitwise (OR) mask of one or more of the following constants
+ * in the Mahoro namespace:
+ *
+ * - APPLE
+ * - CHECK
+ * - COMPRESS
+ * - CONTINUE
+ * - DEBUG
+ * - DEVICES
+ * - ERROR
+ * - MIME
+ * - MIME_ENCODING
+ * - MIME_TYPE
+ * - NONE
+ * - NO_CHECK_APPTYPE
+ * - NO_CHECK_COMPRESS
+ * - NO_CHECK_ELF
+ * - NO_CHECK_ENCODING
+ * - NO_CHECK_SOFT
+ * - NO_CHECK_TAR
+ * - NO_CHECK_TEXT
+ * - NO_CHECK_TOKENS
+ * - PRESERVE_ATIME
+ * - RAW
+ * - SYMLINK
+ */
 static VALUE
 mahoro_set_flags(self, flags)
         VALUE self, flags;
@@ -105,6 +177,14 @@ mahoro_set_flags(self, flags)
         return INT2FIX(magic_setflags(cookie, FIX2INT(flags)));
 }
 
+/*
+ * call-seq:
+ *        mahoro_obj.check(path = nil)        ->        true or false
+ *
+ * This is used to check the validity of entries in the colon separated
+ * database files passed in as +path+.  If +path+ is not passed (or nil),
+ * this will check the default database.
+ */
 static VALUE
 mahoro_check(argc, argv, self)
         int argc;
@@ -129,6 +209,21 @@ mahoro_check(argc, argv, self)
         }
 }
 
+/*
+ * call-seq:
+ *        mahoro_obj.compile(path)        ->        true
+ *
+ * Compile the the colon separated list of database files passed in as +path+.
+ * It returns true on success and raises Mahoro::Error on failure.
+ * Compiled files created are named from the +File.basename+ of each file
+ * argument with ".mgc" appended to it.
+ *
+ * There is no need to use this function if you are using the default magic(5)
+ * database on your operating system.  This is only needed if you require
+ * additional magic not in the default magic database.
+ *
+ * Users of this method are likely to need Mahoro#load (and vice-versa).
+ */
 static VALUE
 mahoro_compile(self, path)
         VALUE self, path;
@@ -142,6 +237,14 @@ mahoro_compile(self, path)
         return Qtrue;
 }
 
+/*
+ * call-seq:
+ *        Mahoro.compile(path)        ->        true
+ *
+ * This is a wrapper around the Mahoro#compile instance method, but does not
+ * require an existing Mahoro object.  Use the instance method unless you only
+ * need to test the validity of a magic(5) database.
+ */
 static VALUE
 mahoro_s_compile(klass, path)
         VALUE klass, path;
@@ -151,6 +254,24 @@ mahoro_s_compile(klass, path)
         return mahoro_compile(m, path);
 }
 
+/*
+ * call-seq:
+ *        mahoro_obj.load(path)        ->        mahoro_obj
+ *
+ * Used to load the the colon-separated list of database files (+path+).
+ * The ".mgc" suffix will be added to each filename where appropriate.
+ * This will raise Mahoro::Error on failure.
+ *
+ * There is no need to use this function if you are using the default magic(5)
+ * database on your operating system.  This is only needed if you require
+ * additional magic not in the default magic database.
+ *
+ * The default database file is named by the MAGIC environment variable.
+ * Consult your libmagic installation documentation for the location of
+ * your default database file name.
+ *
+ * Users of this method are likely to need Mahoro#compile (and vice-versa).
+ */
 static VALUE
 mahoro_load(self, path)
         VALUE self, path;
@@ -166,6 +287,60 @@ mahoro_load(self, path)
 
 void Init_mahoro(void)
 {
+        /*
+         * Mahoro is a simple interface to libmagic.
+         *
+         * Common use cases:
+         *
+         *        # initialize a Mahoro object for reading MIME types
+         *        mahoro_obj = Mahoro.new(Mahoro::MIME)
+         *
+         *        # get the MIME type of a file on disk
+         *        # This is ideal for large files which you do not need to
+         *        # read in their entirety.
+         *        mahoro_obj.file('/path/to/file.c') -> 'text/x-c'
+         *
+         *        # get the MIME type of a string buffer
+         *        # This is only ideal if you already have the buffer in
+         *        # memory or intend to process it soon
+         *        str = File.read('/path/to/file.c')
+         *        mahoro_obj.buffer(str) -> 'text/x-c'
+         *
+         *        # switch the Mahoro object to return an ASCII description
+         *        mahoro_obj.flags = Mahoro::NONE
+         *
+         *        # Similar to the above example, but the Mahoro object
+         *        # now returns a textual        description
+         *        mahoro_obj.file('/path/to/file.c') -> 'ASCII C program text'
+         *
+         *        # Similar to the above example, but the Mahoro object
+         *        # now returns a textual        description
+         *        str = File.read('/path/to/file.c')
+         *        mahoro_obj.buffer(str) -> 'ASCII C program text'
+         *
+         * More information about libmagic:
+         * https://en.wikipedia.org/wiki/Libmagic
+         *
+         * Source code is available via git:
+         *        git clone git://bogomips.org/mahoro.git
+         *
+         * And viewable with a web browser via cgit:
+         *        http://bogomips.org/mahoro.git
+         *
+         * Eric Wong is the current maintainer of Mahoro.
+         * Plain-text comments, questions, bug reports, patches and
+         * pull requests are all highly welcome on the public mailing list:
+         * mahoro@librelist.org
+         *
+         * You may contact Eric privately at normalperson@yhbt.net
+         *
+         * Please generate patches using the "git format-patch" command.
+         * Use of "git send-email" to send a patch is recommended.
+         * For reviewed patches, you may also send a pull request formatted
+         * using the "git request-pull" command.
+         *
+         * Do not expect Eric to read HTML email under any circumstances.
+         */
         cMahoro      = rb_define_class("Mahoro", rb_cObject);
         eMahoroError = rb_define_class_under(cMahoro, "Error", rb_eStandardError);