ruby-dev

Yuguiです。

常々、C APIリファレンスをDoxygenで作りたいと思っていました。YARVで呼び出
し事前条件を持つような関数もかなり増えたことですし、そうした情報を書いて
おけると解析もしやすくて素敵です。

そこで、添付のような形でDoxygen化を試してみました。むやみに全部の関数に
Doxygenコメントを書こうとは思っていませんが、要所要所だけでも書いて知識
を明文化 & 共有したいのですが、どうでしょうか。
採用を検討していただければ幸いです。

== 使い方
* ./configure時にMakefileと一緒にDoxyfileが生成されます
* make install-capiとすると/usr/local/share/doc/ruby/html かどこかにAPI
リファレンスがインストールされます。

== 書き方
/**
 * rdoc
 *--
 * doxygen description
 *++
 */

のように、/**で始まるコメントを処理します。(Doxygenの仕様)
また、rdocによるRubyレベルAPIのリファレンスと共存するために、rdocの非ド
キュメント指定"--" .. "++" で括られた部分をDoxygenに渡すようになっています。

対応するrdocがない関数の場合は
/**
 *--
 * description
 *++
 */

と書けます。また、RDoc::Parser::Cがrdocと間違えるようなコンテキストでな
ければ単に /** description */ のように書けます。

== 制限
処理にそれなりに時間が掛かります。一般ユーザーには必要ないドキュメントで
もありますし、make installではmake install-capiは行わないようにしてあり
ます。


また各ファイルのリビジョンを取得するために、subversionまたはgit svnで
バージョン管理されていることを前提としています。(tool/file2lastrev.rb)
まつもとさんのstgit環境と共存できるかどうかが心配なのですが、stgitとsvn
はどういう形で連携なさってますか?

-- 
Yugui <yugui@yugui.jp>
http://yugui.jp
私は私をDumpする

Attachments (1)

doxygen.diff (15 KB, text/x-diff)

diff --git a/Doxyfile.in b/Doxyfile.in
new file mode 100644
index 0000000..e5a6c0b
--- /dev/null
+++ b/Doxyfile.in
@@ -0,0 +1,251 @@
+# Doxyfile 1.5.7
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = Ruby
+PROJECT_NUMBER         = @MAJOR@.@MINOR@.@TEENY@
+OUTPUT_DIRECTORY       = doc/capi
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = 
+ALWAYS_DETAILED_SEC    = YES
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = 
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                = 
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = NO
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+TYPEDEF_HIDES_STRUCT   = NO
+SYMBOL_CACHE_SIZE      = 0
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = YES
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = NO
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = YES
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_DIRECTORIES       = NO
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    = "@BASERUBY@ @srcdir@/tool/file2lastrev.rb"
+LAYOUT_FILE            = 
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = @srcdir@
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c *.h *.y
+RECURSIVE              = YES
+EXCLUDE                = newline.c 
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = *.src doc build tmp test yarvtest lib bootstraptest spec .ext .git .svn
+EXCLUDE_SYMBOLS        = 
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = 
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = 
+INPUT_FILTER           = "@BASERUBY@ @srcdir@/tool/strip-rdoc.rb"
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = YES
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = NO
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_FOOTER            = 
+HTML_STYLESHEET        = 
+HTML_ALIGN_MEMBERS     = YES
+HTML_DYNAMIC_SECTIONS  = NO
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+GENERATE_HTMLHELP      = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+CHM_INDEX_ENCODING     = 
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+GENERATE_QHP           = NO
+QCH_FILE               = 
+QHP_NAMESPACE          = org.doxygen.Project
+QHP_VIRTUAL_FOLDER     = doc
+QHG_LOCATION           = 
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = NONE
+TREEVIEW_WIDTH         = 250
+FORMULA_FONTSIZE       = 10
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_SCHEMA             = 
+XML_DTD                = 
+XML_PROGRAMLISTING     = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor   
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = 
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references   
+#---------------------------------------------------------------------------
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool   
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = NO
+MSCGEN_PATH            = 
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+DOT_FONTNAME           = FreeSans
+DOT_FONTPATH           = 
+CLASS_GRAPH            = NO
+COLLABORATION_GRAPH    = NO
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = NO
+DIRECTORY_GRAPH        = NO
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine   
+#---------------------------------------------------------------------------
+SEARCHENGINE           = NO
diff --git a/Makefile.in b/Makefile.in
index 39fc686..ab3d8bf 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -164,6 +164,9 @@ fake.rb:	Makefile
 		' > $@
 
 Makefile:	$(srcdir)/Makefile.in $(srcdir)/enc/Makefile.in
+Doxyfile:	$(srcdir)/Doxyfile.in config.status
+	MAKE=$(MAKE) $(SHELL) ./config.status
+	
 
 $(MKFILES): config.status
 		MAKE=$(MAKE) $(SHELL) ./config.status
diff --git a/common.mk b/common.mk
index e170701..feb02e7 100644
--- a/common.mk
+++ b/common.mk
@@ -138,6 +138,8 @@ miniruby$(EXEEXT): config.status $(NORMALMAINOBJ) $(MINIOBJS) $(COMMONOBJS) $(DM
 GORUBY = go$(RUBY_INSTALL_NAME)
 golf: $(LIBRUBY) $(GOLFOBJS)
 	$(MAKE) $(MFLAGS) MAINOBJ="$(GOLFOBJS)" PROGRAM=$(GORUBY)$(EXEEXT) program
+capi: Doxyfile PHONY
+	doxygen
 
 program: $(PROGRAM)
 
@@ -158,7 +160,7 @@ ruby.imp: $(COMMONOBJS)
 	@$(NM) -Pgp $(COMMONOBJS) | awk 'BEGIN{print "#!"}; $$2~/^[BD]$$/{print $$1}' | sort -u -o $@
 
 install: install-nodoc $(RDOCTARGET)
-install-all: install-nodoc install-doc
+install-all: install-nodoc install-doc install-capi
 
 install-nodoc: pre-install-nodoc do-install-nodoc post-install-nodoc
 pre-install-nodoc:: pre-install-local pre-install-ext
@@ -225,6 +227,13 @@ do-install-man: $(PREP)
 post-install-man::
 	@$(NULLCMD)
 
+install-capi: capi pre-install-capi do-install-capi post-install-capi
+pre-install-capi:: install-prereq
+do-install-capi: $(PREP)
+	$(MINIRUBY) $(srcdir)/instruby.rb --make="$(MAKE)" $(INSTRUBY_ARGS) --install=capi
+post-install-capi::
+	@$(NULLCMD)
+
 what-where: no-install
 no-install: no-install-nodoc no-install-doc
 what-where-all: no-install-all
diff --git a/configure.in b/configure.in
index 37a0694..dc9417f 100644
--- a/configure.in
+++ b/configure.in
@@ -2134,6 +2134,10 @@ done
 AC_SUBST(BUILTIN_TRANSSRCS)
 AC_SUBST(BUILTIN_TRANSOBJS)
 
+PACKAGE=$RUBY_INSTALL_NAME
+AC_SUBST(PACKAGE)
+
+AC_CONFIG_FILES(Doxyfile)
 AC_CONFIG_FILES($FIRSTMAKEFILE)
 AC_CONFIG_FILES(Makefile, [{
 	sed '/^MISSING/s/\$U\././g' Makefile
diff --git a/instruby.rb b/instruby.rb
index 3c83dc3..d1796fe 100755
--- a/instruby.rb
+++ b/instruby.rb
@@ -45,7 +45,7 @@ def parse_args(argv = ARGV)
     $mflags.concat(v)
   end
   opt.on('-i', '--install=TYPE',
-         [:local, :bin, :"bin-arch", :"bin-comm", :lib, :man, :ext, :"ext-arch", :"ext-comm", :rdoc]) do |ins|
+         [:local, :bin, :"bin-arch", :"bin-comm", :lib, :man, :ext, :"ext-arch", :"ext-comm", :rdoc, :capi]) do |ins|
     $install << ins
   end
   opt.on('--data-mode=OCTAL-MODE', OptionParser::OctalInteger) do |mode|
@@ -221,6 +221,7 @@ sitearchlibdir = CONFIG["sitearchdir"]
 vendorlibdir = CONFIG["vendorlibdir"]
 vendorarchlibdir = CONFIG["vendorarchdir"]
 mandir = File.join(CONFIG["mandir"], "man")
+capidir = CONFIG["docdir"]
 configure_args = Shellwords.shellwords(CONFIG["configure_args"])
 enable_shared = CONFIG["ENABLE_SHARED"] == 'yes'
 dll = CONFIG["LIBRUBY_SO"]
@@ -400,6 +401,13 @@ install?(:local, :comm, :man) do
     end
   end
 end
+install?(:local, :comm, :capi) do
+  puts "installing capi-docs"
+
+  makedirs [capidir]
+  Dir.chdir("doc")
+  install_recursive "capi", capidir, :mode => $data_mode
+end
 
 $install << :local << :ext if $install.empty?
 $install.each do |inst|
diff --git a/tool/file2lastrev.rb b/tool/file2lastrev.rb
new file mode 100644
index 0000000..f999ea2
--- /dev/null
+++ b/tool/file2lastrev.rb
@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'pathname'
+
+def detect_vcs(path)
+  target_path = Pathname(File.expand_path(path))
+
+  path = target_path.parent
+  begin
+    return :svn, target_path.relative_path_from(path) if File.directory?("#{path}/.svn")
+    return :git, target_path.relative_path_from(path) if File.directory?("#{path}/.git")
+    path, orig = path.parent, path
+  end until path == orig
+  raise "does not seem to be under a vcs"
+end
+
+def get_revisions(path)
+  ENV['LANG'] = ENV['LC_ALL'] = ENV['LC_MESSAGES'] = 'C'
+  vcs, path = detect_vcs(path)
+
+  info = case vcs
+  when :svn
+    `svn info #{path}`
+  when :git
+    `git svn info #{path}`
+  end
+
+  if info =~ /^Revision: (\d+)$/
+    last = $1 
+  else
+    raise "last revision not found"
+  end
+  if info =~ /^Last Changed Rev: (\d+)$/
+    changed = $1
+  else
+    raise "changed revision not found"
+  end
+
+  return last, changed
+end
+
+def raise_if_conflict
+  raise "you can specify only one of -l, -r and -d" if $output
+end
+
+parser = OptionParser.new {|opts|
+  opts.on("-c", "--changed", "changed rev") do
+    raise_if_conflict
+    $output = :changed
+  end
+  opts.on("-r", "--revsion.h") do
+    raise_if_conflict
+    $output = :revision_h
+  end
+  opts.on("-d", "--doxygen") do
+    raise_if_conflict
+    $output = :doxygen
+  end
+}
+parser.parse!
+
+last, changed = get_revisions(ARGV.shift)
+case $output
+when :changed, nil
+  puts changed
+when :revision_h
+  puts "#define RUBY_REVISION #{changed}"
+when :doxygen
+  puts "r#{changed}/r#{last}"
+else
+  raise "unknown output format `#{$output}'"
+end
diff --git a/tool/strip-rdoc.rb b/tool/strip-rdoc.rb
new file mode 100644
index 0000000..205aecc
--- /dev/null
+++ b/tool/strip-rdoc.rb
@@ -0,0 +1,22 @@
+#!ruby
+
+source = ARGF.read
+source = source.gsub(%r{/\*\*((?!\*/).+?)\*/}m) do |comment| 
+  comment = $1
+  next "/**#{comment}*/" unless /^\s*\*\s?\-\-\s*$/ =~ comment
+  doxybody = nil
+  comment.each_line do |line|
+    if doxybody
+      if /^\s*\*\s?\+\+\s*$/ =~ line
+        break
+      end
+      doxybody << line
+    else
+      if /^\s*\*\s?--\s*$/ =~ line
+        doxybody = "\n"
+      end
+    end
+  end
+  "/**#{doxybody}*/"
+end
+print source

Thread

Prev Next

In This Thread

Prev Next