Feature #904: C API reference with Doxygen

• Status: Closed
• Assignee: -
• Target version: -

[yugui (Yuki Sonoda)]

=begin
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 [e-mail]
http://yugui.jp
私は私をDumpする

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 (Phumzani 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
  =end

[matz (Yukihiro Matsumoto)]

=begin
まつもと ゆきひろです

In message "Re: [ruby-dev:37494] [Feature:trunk] C API reference with Doxygen"
on Thu, 18 Dec 2008 18:14:37 +0900, "Yugui (Yuki Sonoda)" [e-mail] writes:

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

ひとつのディレクトリをsvnとgit(stgit)の両方で管理しています。
ですから、リポジトリからの取り込みはsvnコマンドで行っていま
すから、問題は起きないと思いますよ。

=end

[shyouhei (Shyouhei Urabe)]

• Status changed from Open to Closed

=begin

=end