Project

General

Profile

Actions

Feature #904

closed

C API reference with Doxygen

Added by yugui (Yuki Sonoda) over 12 years ago. Updated about 10 years ago.

Status:
Closed
Priority:
Normal
Assignee:
-
Target version:
-
[ruby-dev:37494]

Description

=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 yugui@yugui.jp
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
Actions #1

Updated by matz (Yukihiro Matsumoto) over 12 years ago

=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)" yugui@yugui.jp writes:

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

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

=end

Actions #2

Updated by shyouhei (Shyouhei Urabe) over 12 years ago

  • Status changed from Open to Closed

=begin

=end

Actions

Also available in: Atom PDF