bitclust-core 1.3.0 → 1.6.0

data/lib/bitclust/rrdparser.rb

@@ -12,6 +12,7 @@ require 'bitclust/compat'
 require 'bitclust/preprocessor'
 require 'bitclust/methodid'
 require 'bitclust/methoddatabase'
+require 'bitclust/methodsignature'
 require 'bitclust/lineinput'
 require 'bitclust/parseutils'
 require 'bitclust/nameutils'
@@ -33,21 +34,24 @@ module BitClust
     def RRDParser.parse(s, lib, params = {"version" => "1.9.0"})
       parser = new(MethodDatabase.dummy(params))
       if s.respond_to?(:to_io)
+        # @type var s: File
         io = s.to_io
       elsif s.respond_to?(:to_str)
+        # @type var s: String
         s1 = s.to_str
         require 'stringio'
         io = StringIO.new(s1)
       else
         io = s
       end
+      # @type var io: File | StringIO
       l = parser.parse(io, lib, params)
       return l, parser.db
     end
 
     def RRDParser.split_doc(source)
       if m = /^=(\[a:.*?\])?( +(.*)|([^=].*))\r?\n/.match(source)
-        title = $3 || $4
+        title = $3 || $4 || raise
         s = m.post_match
         return title, s
       end
@@ -141,7 +145,7 @@ module BitClust
       unless m
         parse_error "level-1 header syntax error", line
       end
-      return m[1], isconst(m[2], line), isconst(m[3], line)
+      return (m[1] || raise), isconst((m[2]), line), isconst((m[3]), line)
     end
 
     def isconst(name, line)
@@ -159,7 +163,7 @@ module BitClust
       read_extends f
       read_includes f
       f.skip_blank_lines
-      @context.klass.source = f.break(/\A==?[^=]|\A---/).join('').rstrip
+      @context.klass&.source = f.break(/\A==?[^=]|\A---/).join('').rstrip
       read_level2_blocks f
     end
 
@@ -177,7 +181,7 @@ module BitClust
       f.skip_blank_lines
       read_extends f
       f.skip_blank_lines
-      @context.klass.source = f.break(/\A==?[^=]|\A---/).join('').rstrip
+      @context.klass&.source = f.break(/\A==?[^=]|\A---/).join('').rstrip
       @context.visibility = :public
       @context.type = :singleton_method
       read_level2_blocks f
@@ -219,9 +223,11 @@ module BitClust
       f.while_match(/\A==[^=]/) do |line|
         case line.sub(/\A==/, '').strip
         when /\A((?:public|private|protected)\s+)?(?:(class|singleton|instance)\s+)?methods?\z/i
-          @context.visibility = ($1 || 'public').downcase.intern
+          # @type var visibility: :public | :private | :protected
+          visibility = ($1 || 'public').downcase.strip.intern
+          @context.visibility = visibility
           t = ($2 || 'instance').downcase.sub(/class/, 'singleton')
-          @context.type = "#{t}_method".intern
+          @context.type = _ = "#{t}_method".intern
         when /\AModule\s+Functions?\z/i
           @context.module_function
         when /\AConstants?\z/i
@@ -243,10 +249,10 @@ module BitClust
 
     def concat_aliases(chunks)
       return [] if chunks.empty?
-      result = [chunks.shift]
+      result = [chunks.shift || raise]
       chunks.each do |chunk|
-        if result.last.alias?(chunk)
-          result.last.unify chunk
+        if result.last&.alias?(chunk)
+          result.last&.unify chunk
         else
           result.push chunk
         end
@@ -256,7 +262,7 @@ module BitClust
 
     def read_chunks(f)
       f.skip_blank_lines
-      result = []
+      result = [] #: Array[Chunk]
       f.while_match(/\A---/) do |line|
         f.ungets line
         result.push read_chunk(f)
@@ -264,14 +270,31 @@ module BitClust
       result
     end
 
+    # シグネチャ行に続くメソッド属性行({: ...}。直前のシグネチャ行に束縛)
+    METHOD_ATTRIBUTE_LINE_RE = /\A\{:.*\}[ \t]*$/
+
     def read_chunk(f)
-      header = f.span(/\A---/)
+      # シグネチャ行の直後には {: ...} 属性行を置ける。属性行を挟んでも
+      # ひとつのチャンク(別名グループ)として読む
+      header = [] #: Array[String]
+      sig_lines = [] #: Array[String]
+      while f.next?
+        if /\A---/ =~ f.peek
+          line = f.gets or raise
+          header.push line
+          sig_lines.push line
+        elsif !sig_lines.empty? && METHOD_ATTRIBUTE_LINE_RE =~ f.peek
+          header.push(f.gets || raise)
+        else
+          break
+        end
+      end
       body = f.break(/\A(?:---|={1,2}[^=])/)
       src = (header + body).join('')
-      src.location = header[0].location
-      sigs = header.map {|line| method_signature(line) }
-      mainsig = check_chunk_signatures(sigs, header[0])
-      names = sigs.map {|s| s.name }.uniq.sort
+      src.location = sig_lines[0].location
+      sigs = sig_lines.map {|line| method_signature(line) }
+      mainsig = check_chunk_signatures(sigs, sig_lines[0])
+      names = sigs.map {|s| s.name }.compact.uniq.sort
       Chunk.new(mainsig, names, src)
     end
 
@@ -313,9 +336,12 @@ module BitClust
     def method_signature(line)
       case
       when m = SIGNATURE.match(line)
-        Signature.new(*m.captures)
+        klass, typemark_, name = m.captures
+        # @type var typemark: NameUtils::typemark
+        typemark = _ = typemark_
+        Signature.new(klass, typemark, name)
       when m = GVAR.match(line)
-        Signature.new(nil, '$', m[1][1..-1])
+        Signature.new(nil, '$', (m[1] || raise)[1..-1])
       else
         parse_error "wrong method signature", line
       end
@@ -366,10 +392,13 @@ module BitClust
 
       def define_object(name, singleton_object_class, location: nil)
         singleton_object_class = @db.get_class(singleton_object_class) if singleton_object_class
+        # steep:ignore:start
         register_class :object, name, singleton_object_class, location: location
+        # steep:ignore:end
       end
 
       def register_class(type, name, superclass, location: nil)
+        name or raise
         @klass = @db.open_class(name) {|c|
           c.type = type
           c.superclass = superclass
@@ -401,30 +430,31 @@ module BitClust
       end
 
       def include(name)
-        @klass.include @db.get_class(name)
+        @klass&.include @db.get_class(name)
       end
 
       def extend(name)
-        @klass.extend @db.get_class(name)
+        @klass&.extend @db.get_class(name)
       end
 
       def dynamic_include(name)
-        @klass.dynamic_include(@db.get_class(name), @library)
+        @klass&.dynamic_include(@db.get_class(name), @library)
       end
 
       def dynamic_extend(name)
-        @klass.dynamic_extend(@db.get_class(name), @library)
+        @klass&.dynamic_extend(@db.get_class(name), @library)
       end
 
       # Add a alias +name+ to the alias list.
       def alias(name)
+        klass = @klass || raise
         @db.open_class(name) do |c|
-          c.type = @klass.type
+          c.type = klass.type
           c.library = @library
-          c.aliasof = @klass
-          c.source = "Alias of [[c:#{@klass.name}]]\n"
+          c.aliasof = klass
+          c.source = "Alias of [[c:#{klass.name}]]\n"
           @library.add_class c
-          @klass.alias c
+          klass.alias c
         end
       end
 
@@ -437,7 +467,7 @@ module BitClust
       end
 
       def special_variable
-        unless @klass and @klass.name == 'Kernel'
+        unless @klass and @klass&.name == 'Kernel'
           raise "must not happen: type=special_variable but class!=Kernel"
         end
         @type = :special_variable
@@ -445,17 +475,30 @@ module BitClust
 
       def signature
         return nil unless @klass
-        Signature.new(@klass.name, @type ? typename2mark(@type) : nil, nil)
+        Signature.new(@klass&.name, @type ? typename2mark(@type || raise) : nil, nil)
       end
 
       def define_method(chunk)
         id = method_id(chunk)
+        attrs = method_attributes(chunk)
         @db.open_method(id) {|m|
           m.names           = chunk.names.sort
-          m.kind            = chunk.source.match?(/^@undef$/) ? :undefined : @kind
+          m.kind            = if attrs.flags.include?('undef')
+                                :undefined
+                              elsif attrs.flags.include?('nomethod')
+                                :nomethod
+                              else
+                                @kind
+                              end
+          # steep:ignore:start
           m.visibility      = @visibility || :public
+          # steep:ignore:end
           m.source          = chunk.source
           m.source_location = chunk.source.location
+          attrs.since_until.each do |name, kv|
+            m.fill_since(name, kv['since'] || raise) if kv['since']
+            m.fill_until(name, kv['until'] || raise) if kv['until']
+          end
           case @kind
           when :added, :redefined
             @library.add_method m
@@ -463,10 +506,133 @@ module BitClust
         }
       end
 
+      # 現在サポートするメソッド属性({: ...} 属性行のトークン)。
+      # - nomethod/undef: 裸語。kind はエントリ単位でしか持てないので、
+      #   別名(複数シグネチャ)のエントリでは全シグネチャに同じ属性が
+      #   付いていることを要求する
+      # - since="X"/until="X"(bitclust#132 P4): シグネチャ単位で束縛され、
+      #   そのシグネチャの名前だけに適用される。nomethod/undef と違い、
+      #   別名ごとに異なる値を持てる(全シグネチャ一致は要求しない)のが
+      #   本来の用途。X は "3.2" のように数字とドットのみ。
+      #   空値(since="")は「明示的に不明」= バッジ非表示の指定で、メソッド
+      #   自体は昔からあるのにドキュメント追加が遅れ、バージョンラダーからの
+      #   自動算出が誤った版を出す場合の抑止に使う(空文字が記録されるため
+      #   算出値で上書きされず、表示側も空はバッジを出さない)
+      METHOD_ATTRIBUTES = %w[nomethod undef]
+      KV_METHOD_ATTRIBUTES = %w[since until]
+      KV_METHOD_ATTRIBUTE_VALUE_RE = /\A(?:\d+(?:\.\d+)*)?\z/
+
+      # md の `### def name ...`/`### module_function def name ...`/
+      # `### const name`/`### gvar $name` シグネチャ行を rd 形式
+      # (`--- name ...`)へ正規化するための接頭辞(MDParser::SIG_RE と
+      # 同じパターン)。属性の紐付け先となるメソッド名を
+      # MethodSignature.parse で取り出すために使う
+      MD_METHOD_SIG_PREFIX_RE = /\A### (?:module_function def |def |const |gvar )/
+
+      # method_attributes の返り値。
+      # - flags: 裸語トークン(nomethod/undef)の集合。エントリ単位の属性
+      #   なので全シグネチャで同一であることを method_attributes が保証済み
+      # - since_until: シグネチャ単位で束縛された since="X"/until="X" を
+      #   { メソッド名 => { "since" => "X", "until" => "X" } } の形で保持する
+      MethodAttributes = Struct.new(:flags, :since_until)
+
+      # kramdown Block IAL 風の {: ...} 属性行からメタデータを集める。
+      # 属性行は「直前のシグネチャ行のみ」に束縛される(kramdown と同じ解釈)。
+      # 裸語トークン(nomethod/undef)は kind がエントリ単位でしか持てないため
+      # 全シグネチャで同じであることを要求するが、since=/until= はシグネチャ
+      # 単位でそのままの名前に適用するため、この一致要求からは除外する。
+      # 本文に入ったら探索を打ち切る(コード例中の {: ...} を誤検出しないため)
+      def method_attributes(chunk)
+        per_sig = [] #: Array[Array[String]]
+        since_until = {} #: Hash[String, Hash[String, String]]
+        current_name = nil #: String?
+        current_keys = nil #: Hash[String, bool]?
+        chunk.source.each_line do |line_|
+          line = line_.chomp
+          case line
+          when /\A---\s/, /\A\#\#\#\s/
+            per_sig.push []
+            current_name = method_attribute_target_name(line)
+            current_keys = {}
+          when /\A\{:(.*)\}[ \t]*\z/
+            break if per_sig.empty?
+            ($1 || raise).strip.split(/\s+/).each do |token|
+              if METHOD_ATTRIBUTES.include?(token)
+                per_sig.last&.push token
+              else
+                key, value = parse_kv_method_attribute(token, chunk)
+                keys = current_keys or raise
+                if keys.key?(key)
+                  raise ParseError,
+                        "#{chunk.source.location}: duplicate method attribute #{key.inspect} on the same signature"
+                end
+                keys[key] = true
+                name = current_name or
+                  raise ParseError,
+                        "#{chunk.source.location}: cannot determine the signature name to bind method attribute #{token.inspect} to"
+                (since_until[name] ||= {})[key] = value
+              end
+            end
+          else
+            break
+          end
+        end
+        return MethodAttributes.new([], {}) if per_sig.empty?
+        sets = per_sig.map {|a| a.uniq.sort }
+        unless sets.uniq.size == 1
+          raise ParseError,
+                "#{chunk.source.location}: method attributes must be the same on every signature of an entry: #{sets.inspect}"
+        end
+        # 紐付け先の名前がエントリの names と食い違ったら黙って捨てずに
+        # エラーにする(名前導出の規約ずれを CI で検出するための安全網)
+        since_until.each_key do |name|
+          unless chunk.names.include?(name)
+            raise ParseError,
+                  "#{chunk.source.location}: since/until attribute bound to unknown signature name #{name.inspect} (entry names: #{chunk.names.join(', ')})"
+          end
+        end
+        MethodAttributes.new(sets.first || raise, since_until)
+      end
+
+      # since="X"/until="X" 形式のトークンを解析して [key, value] を返す。
+      # 受理する形式以外(キーが不明・値が非引用・値が数字とドット以外を
+      # 含む等)はすべて ParseError にする
+      def parse_kv_method_attribute(token, chunk)
+        m = /\A(\w+)=(.*)\z/.match(token)
+        if m
+          key = m[1] || raise
+          raw_value = m[2] || raise
+          quoted = /\A"(.*)"\z/.match(raw_value)
+          if quoted && KV_METHOD_ATTRIBUTES.include?(key) && KV_METHOD_ATTRIBUTE_VALUE_RE.match?(quoted[1] || raise)
+            return [key, (quoted[1] || raise)]
+          end
+        end
+        raise ParseError,
+              "#{chunk.source.location}: invalid method attribute #{token.inspect} " \
+              "(supported: #{METHOD_ATTRIBUTES.join(', ')}, " \
+              "#{KV_METHOD_ATTRIBUTES.map {|k| %Q(#{k}="X") }.join('/')} where X is digits and dots, e.g. since=\"3.2\", " \
+              "or empty for explicitly-unknown, e.g. since=\"\")"
+      end
+      private :parse_kv_method_attribute
+
+      # シグネチャ行(rd の `--- ...` / md の `### def ...` 等)から、
+      # 属性の紐付け先となるメソッド名を取り出す。
+      # 特殊変数のシグネチャ名は "$SAFE" のように $ 付きだが、エントリの
+      # names は先頭の $ を除いた形("SAFE"。"$$" なら "$")で格納される
+      # (method_signature の Signature.new(nil, '$', name[1..-1]) と同じ規約)
+      # ため、since_by_name のキーも names に合わせて $ を1つ剥がす
+      def method_attribute_target_name(line)
+        normalized = line.sub(MD_METHOD_SIG_PREFIX_RE, '--- ')
+        MethodSignature.parse(normalized).name.sub(/\A\$/, '')
+      rescue ParseError
+        nil
+      end
+      private :method_attribute_target_name
+
       def method_id(chunk)
         id = MethodID.new
         id.library = @library
-        id.klass   = chunk.signature.klass ? @db.get_class(chunk.signature.klass) : @klass
+        id.klass   = chunk.signature.klass ? @db.get_class(chunk.signature.klass) : (@klass || raise)
         id.type    = chunk.signature.typename || @type
         id.name    = chunk.names.sort.first
         id
@@ -521,7 +687,7 @@ module BitClust
       end
 
       def typename
-        typemark2name(@type)
+        typemark2name(_ = @type)
       end
 
       def same_type?(other)

data/lib/bitclust/runner.rb

@@ -3,7 +3,7 @@ require 'pathname'
 require 'optparse'
 
 unless Object.const_defined?(:Encoding)
-  $KCODE = 'UTF-8'
+  $KCODE = 'UTF-8' # steep:ignore
 end
 
 def libdir
@@ -50,6 +50,7 @@ Subcommands(for users):
     list        List libraries/classes/methods in database.
     lookup      Lookup a library/class/method from database.
     search      Search classes/methods from database.
+    server      Run HTTP server to browse the reference manual.
 
 Subcommands(for developers):
     ancestors   Compare class/module's ancestors between Ruby and DB.
@@ -60,9 +61,12 @@ Subcommands(for developers):
     extract     Extract method entries from source file.
     classes     Display defined classes for all ruby.
     methods     Display defined methods for all ruby.
+    methodsince Fill per-name since/until from a version ladder of DBs.
+    checklink   Report broken [[c:]]/[[m:]]/[[lib:]]/[[d:]]/[[f:]] links.
 
 Subcommands(for packagers):
     statichtml  Generate static HTML files.
+    searchpage  Generate a static cross-version search page.
     epub        Generate EPUB file.
     chm         Generate static HTML files for CHM.
 
@@ -96,6 +100,7 @@ Global Options:
         'setup'       => BitClust::Subcommands::SetupCommand.new,
         'server'      => BitClust::Subcommands::ServerCommand.new,
         'statichtml'  => BitClust::Subcommands::StatichtmlCommand.new,
+        'searchpage'  => BitClust::Subcommands::SearchpageCommand.new,
         'htmlfile'    => BitClust::Subcommands::HtmlfileCommand.new,
         'chm'         => BitClust::Subcommands::ChmCommand.new,
         'epub'        => BitClust::Subcommands::EPUBCommand.new,
@@ -104,6 +109,8 @@ Global Options:
         'extract'     => BitClust::Subcommands::ExtractCommand.new,
         'classes'     => BitClust::Subcommands::ClassesCommand.new,
         'methods'     => BitClust::Subcommands::MethodsCommand.new,
+        'methodsince' => BitClust::Subcommands::MethodsinceCommand.new,
+        'checklink'   => BitClust::Subcommands::ChecklinkCommand.new,
       }
     end
 
@@ -134,6 +141,14 @@ Global Options:
         @version ||= config[:default_version]
         @prefix ||= "#{config[:database_prefix]}-#{@version}"
       end
+      # DB 必須のサブコマンドで --database も ~/.bitclust/config も無ければ
+      # 案内付きで中断する。needs_database? が false のサブコマンドと、
+      # 自前で DB を探す search (Searcher) は対象外
+      needs_database = cmd.respond_to?(:needs_database?) && cmd.needs_database?
+      if needs_database && !@prefix
+        error "no database given. Use --database (-d) option or ~/.bitclust/config"
+      end
+      # @type var options: Subcommand::options
       options = {
         :prefix => @prefix,
         :capi   => @capi
@@ -145,7 +160,7 @@ Global Options:
     end
 
     def load_config
-      home_directory = Pathname(ENV['HOME'])
+      home_directory = Pathname(ENV.fetch('HOME'))
       config_path = home_directory + ".bitclust/config"
       if config_path.exist?
         YAML.load_file(config_path)

data/lib/bitclust/screen.rb

@@ -13,6 +13,7 @@ require 'bitclust/methodsignature'
 require 'bitclust/htmlutils'
 require 'bitclust/nameutils'
 require 'bitclust/messagecatalog'
+require 'bitclust/version_badges'
 require 'erb'
 require 'json'
 require 'stringio'
@@ -37,6 +38,7 @@ module BitClust
     private :default_message_catalog
 
     def entry_screen(entry, opt)
+      @conf[:target_version] = opt[:target_version]
       new_screen(Screen.for_entry(entry), entry, opt)
     end
 
@@ -141,7 +143,7 @@ module BitClust
     end
 
     def method_url(spec)
-      cname, tmark, mname = *split_method_spec(spec)
+      cname, tmark, mname = split_method_spec(spec)
       "#{@cgi_url}/method/#{classname2id(cname)}/#{typemark2char(tmark)}/#{encodename_url(mname)}"
     end
 
@@ -188,7 +190,7 @@ module BitClust
     private
 
     def preproc(template)
-      template.gsub(/^\.include ([\w\-]+)/) { load($1) }
+      template.gsub(/^\.include ([\w\-]+)/) { load($1 || raise) }
     end
   end
 
@@ -226,7 +228,7 @@ module BitClust
 <body>
 <h1>Error</h1>
 <pre>#{escape_html(@error.message)} (#{escape_html(@error.class.name)})
-#{@error.backtrace.map {|s| escape_html(s) }.join("\n")}</pre>
+#{@error.backtrace&.map {|s| escape_html(s) }&.join("\n")}</pre>
 </body>
 </html>
       EndHTML
@@ -264,6 +266,7 @@ module BitClust
   class TemplateScreen < Screen
     include Translatable
     include HTMLUtils
+    include VersionBadges
 
     def initialize(h)
       @urlmapper = h[:urlmapper]
@@ -313,6 +316,19 @@ module BitClust
       %Q(<meta name="description" content="">)
     end
 
+    # True when the build was told (via statichtml --eol-warning) that the
+    # documented Ruby version is no longer maintained.
+    def eol_warning?
+      !!@conf[:eol_warning]
+    end
+
+    # URL of the ruby.wasm module used by the in-browser RUN button on Ruby
+    # sample code (statichtml --run-ruby-wasm). nil disables the feature.
+    def run_ruby_wasm_url
+      url = @conf[:run_ruby_wasm] #: String?
+      url
+    end
+
     private
 
     def default_encoding
@@ -357,6 +373,12 @@ module BitClust
       @urlmapper.custom_js_url(js)
     end
 
+    # Relative path from the current page to the site root, used as the
+    # prefix for client-side search result links in statichtml output.
+    def html_base
+      @urlmapper.respond_to?(:bitclust_html_base) ? @urlmapper.bitclust_html_base : '.'
+    end
+
     def favicon_url
       @urlmapper.favicon_url
     end
@@ -453,16 +475,55 @@ module BitClust
       rdcompiler().compile(src)
     end
 
+    # DB が Markdown ソース（update --markdowntree のネイティブパース）なら
+    # MDCompiler（GFM モード）で描画する
+    def markdown_source?
+      db = @conf[:database]
+      db && db.properties['source_format'] == 'markdown'
+    end
+
     def rdcompiler
-      opt = {:catalog => message_catalog()}.merge(@conf)
-      RDCompiler.new(@urlmapper, @hlevel, opt)
+      opt = {:catalog => message_catalog()}.merge(@conf) #: RDCompiler::option
+      if markdown_source?
+        require 'bitclust/mdcompiler'
+        gfm_opt = opt.merge(:gfm => true) #: RDCompiler::option
+        MDCompiler.new(@urlmapper, @hlevel, gfm_opt)
+      else
+        RDCompiler.new(@urlmapper, @hlevel, opt)
+      end
+    end
+
+    # bitclust#132 P3: data/bitclust/template/class の署名欄で使う。この
+    # テンプレートは compile_method(RDCompiler)を経由せず自前でシグネチャを
+    # 描画するので、別名(alias)ごとに自分の since/until バッジを付けた
+    # <a><code>...</code></a> を1行ずつ組み立て、<br> で連結する
+    def method_row_signature_html(m, sigs)
+      sigs.map {|sig|
+        %Q(<a href="#{h(method_url(m.spec_string))}"><code>#{h(sig.friendly_string)}</code></a>) +
+          row_version_badges(m, sig.name)
+      }.join('<br>')
     end
 
     def foreach_method_chunk(src)
+      require 'bitclust/mdparser' if markdown_source?
+      sig_re = markdown_source? ? MDParser::SIG_RE : /\A---/
       f = LineInput.for_string(src)
       while f.next?
-        sigs = f.span(/\A---/).map {|line| MethodSignature.parse(line.rstrip) }
-        body = f.break(/\A---/).join.split(/\n\n/, 2).first || ''
+        # シグネチャ行の直後の {: ...} メソッド属性行はシグネチャブロックの
+        # 一部として読み飛ばす(シグネチャにも本文にも含めない)
+        sigs = [] #: Array[MethodSignature]
+        while f.next?
+          if sig_re =~ f.peek
+            line = f.gets or raise
+            line = line.sub(sig_re, '--- ') if markdown_source?
+            sigs.push MethodSignature.parse(line.rstrip)
+          elsif !sigs.empty? && /\A\{:.*\}[ \t]*$/ =~ f.peek
+            f.gets
+          else
+            break
+          end
+        end
+        body = f.break(sig_re).join.split(/\n\n/, 2).first || ''
         yield sigs, body
       end
     end
@@ -541,14 +602,16 @@ module BitClust
     def draw_tree(cs, &block)
       return if cs.empty?
       if cs.first.class?
-        tree = cs.group_by{|c| c.superclass }
+        tree = cs.group_by{|c| c.superclass } # steep:ignore
         tree.each {|key, list| list.sort_by!{|c| c ? c.name : "" } }
         roots = tree.keys.select{|c| !c || !cs.include?(c) }
-        roots.map!{|c| tree[c] }.flatten!
+        roots.map!{|c| tree[c] }.flatten! # steep:ignore
       else
         tree = {}
         roots = cs
       end
+      # @type var roots: Array[ClassEntry]
+      # @type var tree: Hash[ClassEntry, Array[ClassEntry]]
       draw_treed_entries(roots, tree, &block)
     end
 
@@ -683,8 +746,14 @@ module BitClust
     end
 
     def rdcompiler
-      h = {:force => true, :catalog => message_catalog() }.merge(@conf)
-      RDCompiler.new(@urlmapper, @hlevel, h)
+      h = {:force => true, :catalog => message_catalog() }.merge(@conf) #: RDCompiler::option
+      if markdown_source?
+        require 'bitclust/mdcompiler'
+        gfm_opt = h.merge(:gfm => true) #: RDCompiler::option
+        MDCompiler.new(@urlmapper, @hlevel, gfm_opt)
+      else
+        RDCompiler.new(@urlmapper, @hlevel, h)
+      end
     end
 
     def current_url