From bfcb5763186ac6902ce431ef78732efd9f09f194 Mon Sep 17 00:00:00 2001 From: tak Date: Wed, 2 Jan 2008 17:56:56 +0000 Subject: [PATCH] Updated documentation formatting --- ruby-lightmediascanner/gendocs.sh | 6 ++ .../lightmediascanner-unittest.rb | 1 + ruby-lightmediascanner/lightmediascanner_parser.c | 20 +++++- ruby-lightmediascanner/lightmediascanner_scanner.c | 69 ++++++++++++++++---- ruby-lightmediascanner/ruby-lightmediascanner.c | 8 +++ 5 files changed, 90 insertions(+), 14 deletions(-) create mode 100755 ruby-lightmediascanner/gendocs.sh diff --git a/ruby-lightmediascanner/gendocs.sh b/ruby-lightmediascanner/gendocs.sh new file mode 100755 index 0000000..945c76d --- /dev/null +++ b/ruby-lightmediascanner/gendocs.sh @@ -0,0 +1,6 @@ +#!/bin/sh + +rm -rf doc +cat ruby-lightmediascanner.c lightmediascanner*c > rdoc.c +rdoc +rm rdoc.c diff --git a/ruby-lightmediascanner/lightmediascanner-unittest.rb b/ruby-lightmediascanner/lightmediascanner-unittest.rb index 508cce6..a144c81 100755 --- a/ruby-lightmediascanner/lightmediascanner-unittest.rb +++ b/ruby-lightmediascanner/lightmediascanner-unittest.rb @@ -25,6 +25,7 @@ require 'lightmediascanner' if(__FILE__ == $0) require 'test/unit' + # Test cases for LightMediaScanner. You probably don't care about this. class LightMediaScanner::Test < Test::Unit::TestCase include LightMediaScanner diff --git a/ruby-lightmediascanner/lightmediascanner_parser.c b/ruby-lightmediascanner/lightmediascanner_parser.c index d23c66f..e48c5c5 100644 --- a/ruby-lightmediascanner/lightmediascanner_parser.c +++ b/ruby-lightmediascanner/lightmediascanner_parser.c @@ -26,9 +26,11 @@ typedef struct { } ParserRuby; /** + * * Native memory deletion function - * @param self The current Parser instance + * * @return nil + * */ static VALUE parser_free(VALUE self) { ParserRuby *parser; @@ -46,10 +48,13 @@ static VALUE parser_free(VALUE self) { #if 0 // Obsolete /** + * * Add parser plugin, given its shared object path. - * @param self The current Parser instance + * * @param name path to shared object (usable by dlopen(3)). + * * @return A new Parser + * */ static VALUE scanner_add_parser(VALUE self, VALUE name) { lms_t *lms; @@ -74,12 +79,17 @@ static VALUE scanner_add_parser(VALUE self, VALUE name) { #endif /** + * * Parser#new + * * constructor - * @param obj The LightMediaScanner::Parser class + * * @param parent The Scanner to which the parser belongs + * * @param name path to shared object (usable by dlopen(3)). + * * @return A new Parser + * */ static VALUE parser_new(VALUE obj, VALUE parent, VALUE name) { lms_t *lms; @@ -106,6 +116,10 @@ static VALUE parser_new(VALUE obj, VALUE parent, VALUE name) { return Data_Wrap_Struct(lightmediascanner_parser, 0, parser_free, parser); }// scanner_new +/** + * LightMediaScanner::Parser is a class to represent + * a LightMediaScanner plugin. + */ void Init_lightmediascanner_parser() { lightmediascanner_parser = rb_define_class_under(lightmediascanner_module, "Parser", rb_cObject); rb_define_singleton_method(lightmediascanner_parser, "new", parser_new, 2); diff --git a/ruby-lightmediascanner/lightmediascanner_scanner.c b/ruby-lightmediascanner/lightmediascanner_scanner.c index af953c8..6547a44 100644 --- a/ruby-lightmediascanner/lightmediascanner_scanner.c +++ b/ruby-lightmediascanner/lightmediascanner_scanner.c @@ -18,13 +18,16 @@ * @author Levi Bard */ +#include "ruby-lightmediascanner.h" #include "lightmediascanner_scanner.h" /** * Scanner#new + * * constructor - * @param obj The LightMediaScanner::Scanner class + * * @param db_path The path to the sqlite3 db to be used + * * @return A new Scanner instance */ static VALUE scanner_new(VALUE obj, VALUE db_path) { @@ -33,11 +36,15 @@ static VALUE scanner_new(VALUE obj, VALUE db_path) { }// scanner_new /** + * * Scanner::process + * * This will add or update media found in the given directory or its children. - * @param self The current Scanner instance + * * @param top_path The top directory to scan. + * * @return 0 on success + * */ static VALUE scanner_process(VALUE self, VALUE top_path) { lms_t *lms; @@ -58,11 +65,15 @@ static VALUE scanner_process(VALUE self, VALUE top_path) { }// scanner_process /** + * * Scanner::check + * * Check consistency of the given directory. - * @param self The current Scanner instance + * * @param top_path The top directory to scan. + * * @return 0 on success + * */ static VALUE scanner_check(VALUE self, VALUE top_path) { lms_t *lms; @@ -83,10 +94,13 @@ static VALUE scanner_check(VALUE self, VALUE top_path) { }// scanner_check /** + * * Scanner::db_path + * * Accessor for LMS DB path. - * @param self The current Scanner instance + * * @return The database path given at creation time + * */ static VALUE scanner_db_path(VALUE self) { lms_t *lms; @@ -96,10 +110,13 @@ static VALUE scanner_db_path(VALUE self) { }// scanner_db_path /** + * * Scanner::processing? + * * Checks if Light Media Scanner is being used in a processing operation like lms_process() or lms_check(). - * @param self The current Scanner instance + * * @return Boolean representing the instance's processing state + * */ static VALUE scanner_processing(VALUE self) { lms_t *lms; @@ -109,11 +126,15 @@ static VALUE scanner_processing(VALUE self) { }// scanner_processing /** + * * Scanner::timeout + * * Get the maximum amount of milliseconds the slave can take to serve one file. + * * If a slave takes more than this amount of milliseconds, it will be killed and the scanner will continue with the next file. - * @param self The current Scanner instance + * * @return The timeout in milliseconds, or -1 on error + * */ static VALUE scanner_get_slave_timeout(VALUE self) { lms_t *lms; @@ -123,12 +144,17 @@ static VALUE scanner_get_slave_timeout(VALUE self) { }// scanner_get_slave_timeout /** + * * Scanner::timeout= + * * Set the maximum amount of milliseconds the slave can take to serve one file. + * * If a slave takes more than this amount of milliseconds, it will be killed and the scanner will continue with the next file. - * @param self The current Scanner instance + * * @param timeout_ms The timeout in milliseconds + * * @return The new timeout, in milliseconds + * */ static VALUE scanner_set_slave_timeout(VALUE self, VALUE timeout_ms) { lms_t *lms; @@ -141,10 +167,13 @@ static VALUE scanner_set_slave_timeout(VALUE self, VALUE timeout_ms) { }// scanner_set_slave_timeout /** + * * Scanner::commit_interval + * * Get the number of files served between database transactions. - * @param self The current Scanner instance + * * @return The number of files served between database transactions + * */ static VALUE scanner_get_commit_interval(VALUE self) { lms_t *lms; @@ -154,11 +183,15 @@ static VALUE scanner_get_commit_interval(VALUE self) { }// scanner_get_commit_interval /** + * * Scanner::commit_interval= + * * Set the number of files to be served between database transactions. - * @param self The current Scanner instance + * * @param transactions The number of files between commits + * * @return The new number of files to be served between database transactions + * */ static VALUE scanner_set_commit_interval(VALUE self, VALUE transactions) { lms_t *lms; @@ -171,12 +204,17 @@ static VALUE scanner_set_commit_interval(VALUE self, VALUE transactions) { }// scanner_set_commit_interval /** + * * Scanner::add_charset + * * Register a new charset encoding to be used. + * * Throws a RuntimeError if LMS is unable to add the charset. - * @param self The current Scanner instance + * * @param charset charset name as understood by iconv_open(3). + * * @return charset + * */ static VALUE scanner_add_charset(VALUE self, VALUE charset) { lms_t *lms; @@ -194,12 +232,17 @@ static VALUE scanner_add_charset(VALUE self, VALUE charset) { }// scanner_add_charset /** + * * Scanner::remove_charset + * * Forget about a registered charset encoding. + * * Throws a RuntimeError if LMS is unable to remove the charset. - * @param self The current Scanner instance + * * @param charset charset name as understood by iconv_open(3). + * * @return charset + * */ static VALUE scanner_remove_charset(VALUE self, VALUE charset) { lms_t *lms; @@ -215,6 +258,10 @@ static VALUE scanner_remove_charset(VALUE self, VALUE charset) { return charset; }// scanner_remove_charset +/** + * LightMediaScanner::Scanner is a class to represent a + * LightMediaScanner instance. + */ void Init_lightmediascanner_scanner() { lightmediascanner_scanner = rb_define_class_under(lightmediascanner_module, "Scanner", rb_cObject); rb_define_singleton_method(lightmediascanner_scanner, "new", scanner_new, 1); diff --git a/ruby-lightmediascanner/ruby-lightmediascanner.c b/ruby-lightmediascanner/ruby-lightmediascanner.c index b707af1..54f243f 100644 --- a/ruby-lightmediascanner/ruby-lightmediascanner.c +++ b/ruby-lightmediascanner/ruby-lightmediascanner.c @@ -20,6 +20,14 @@ #include "ruby-lightmediascanner.h" +/** + * LightMediaScanner is the outer module of the + * LightMediaScanner Ruby extension. + * + * It doesn't currently perform any function other than + * namespacing. You probably want to see LightMediaScanner::Scanner + * and LightMediaScanner::Parser . + */ void Init_lightmediascanner() { lightmediascanner_module = rb_define_module("LightMediaScanner"); Init_lightmediascanner_scanner(); -- 1.7.9.5