jsduck 2.0.pre4 → 3.0.pre

data/lib/jsduck/app.rb

@@ -3,136 +3,108 @@ require 'jsduck/aggregator'
 require 'jsduck/source_file'
 require 'jsduck/source_writer'
 require 'jsduck/doc_formatter'
+require 'jsduck/class_formatter'
 require 'jsduck/class'
-require 'jsduck/tree'
-require 'jsduck/tree_icons'
+require 'jsduck/icons'
 require 'jsduck/search_data'
 require 'jsduck/relations'
 require 'jsduck/aliases'
 require 'jsduck/exporter'
+require 'jsduck/renderer'
 require 'jsduck/timer'
 require 'jsduck/parallel_wrap'
 require 'jsduck/logger'
+require 'jsduck/welcome'
 require 'jsduck/guides'
+require 'jsduck/videos'
+require 'jsduck/examples'
 require 'jsduck/categories'
-require 'jsduck/jsonp'
-require 'json'
+require 'jsduck/json_duck'
+require 'jsduck/lint'
 require 'fileutils'
 
 module JsDuck
 
   # The main application logic of jsduck
   class App
-    # These are basically input parameters for app
-    attr_accessor :output_dir
-    attr_accessor :template_dir
-    attr_accessor :guides_dir
-    attr_accessor :guides_order
-    attr_accessor :categories_path
-    attr_accessor :template_links
-    attr_accessor :input_files
-    attr_accessor :export
-    attr_accessor :link_tpl
-    attr_accessor :img_tpl
-    attr_accessor :ignore_global
-    attr_accessor :external_classes
-    attr_accessor :show_private_classes
-    attr_accessor :title
-    attr_accessor :footer
-    attr_accessor :extjs_path
-    attr_accessor :local_storage_db
-    attr_accessor :head_html
-    attr_accessor :body_html
-
-    def initialize
-      @output_dir = nil
-      @template_dir = nil
-      @guides_dir = nil
-      @guides_order = nil
-      @categories_path = nil
-      @template_links = false
-      @input_files = []
-      @warnings = true
-      @export = nil
-      @link_tpl = nil
-      @img_tpl = nil
-      @ignore_global = false
-      @external_classes = []
-      @show_private_classes = false
-      @title = "Ext JS API Documentation"
-      @footer = 'Generated with <a href="https://github.com/senchalabs/jsduck">JSDuck</a>.'
-      @extjs_path = "extjs/ext-all.js"
-      @local_storage_db = "docs"
-      @head_html = ""
-      @body_html = ""
+    # Initializes app with JsDuck::Options object
+    def initialize(opts)
+      @opts = opts
       @timer = Timer.new
-      @parallel = ParallelWrap.new
-    end
-
-    # Sets the nr of parallel processes to use.
-    # Set to 0 to disable parallelization completely.
-    def processes=(count)
-      @parallel = ParallelWrap.new(:in_processes => count)
-    end
-
-    # Sets warnings on or off
-    def warnings=(enabled)
-      Logger.instance.warnings = enabled
-    end
-
-    # Sets verbose mode on or off
-    def verbose=(enabled)
-      Logger.instance.verbose = enabled
+      # Sets the nr of parallel processes to use.
+      # Set to 0 to disable parallelization completely.
+      @parallel = ParallelWrap.new(:in_processes => @opts.processes)
+      # Sets warnings and verbose mode on or off
+      Logger.instance.warnings = @opts.warnings
+      Logger.instance.verbose = @opts.verbose
+      # Turn JSON pretty-printing on/off
+      JsonDuck.pretty = @opts.pretty_json
     end
 
     # Call this after input parameters set
     def run
-      # Set default templates
-      @link_tpl ||= '<a href="#/api/%c%-%m" rel="%c%-%m" class="docClass">%a</a>'
-      # Note that we wrap image template inside <p> because {@img} often
-      # appears inline within text, but that just looks ugly in HTML
-      @img_tpl ||= '<p><img src="doc-resources/%u" alt="%a"></p>'
-
-      parsed_files = @timer.time(:parsing) { parallel_parse(@input_files) }
+      parsed_files = @timer.time(:parsing) { parallel_parse(@opts.input_files) }
       result = @timer.time(:aggregating) { aggregate(parsed_files) }
-      relations = @timer.time(:aggregating) { filter_classes(result) }
-      Aliases.new(relations).resolve_all
-      warn_globals(relations)
-      warn_unnamed(relations)
+      @relations = @timer.time(:aggregating) { filter_classes(result) }
+      Aliases.new(@relations).resolve_all
+      Lint.new(@relations).run
 
-      @guides = Guides.new(get_doc_formatter(relations), @guides_order)
-      if @guides_dir
-        @timer.time(:parsing) { @guides.parse_dir(@guides_dir) }
+      @welcome = Welcome.new
+      if @opts.welcome
+        @timer.time(:parsing) { @welcome.parse(@opts.welcome) }
       end
 
-      @categories = Categories.new(get_doc_formatter(relations), relations)
-      if @categories_path
+      @guides = Guides.new(get_doc_formatter)
+      if @opts.guides
+        @timer.time(:parsing) { @guides.parse(@opts.guides) }
+      end
+
+      @videos = Videos.new
+      if @opts.videos
+        @timer.time(:parsing) { @videos.parse(@opts.videos) }
+      end
+
+      @examples = Examples.new
+      if @opts.examples
+        @timer.time(:parsing) { @examples.parse(@opts.examples) }
+      end
+
+      @categories = Categories.new(get_doc_formatter, @relations)
+      if @opts.categories_path
         @timer.time(:parsing) do
-          @categories.parse(@categories_path)
+          @categories.parse(@opts.categories_path)
           @categories.validate
         end
       end
 
-      clear_dir(@output_dir) unless @export == :stdout
-      if @export == :stdout
-        @timer.time(:generating) { puts JSON.generate(relations.classes) }
-      elsif @export == :json
-        FileUtils.mkdir(@output_dir)
-        init_output_dirs(@output_dir)
-        @timer.time(:generating) { write_src(@output_dir+"/source", parsed_files) }
-        @timer.time(:generating) { write_classes(@output_dir+"/output", relations) }
+      clear_output_dir unless @opts.export == :stdout
+      if @opts.export == :stdout
+        @timer.time(:generating) { puts JsonDuck.generate(@relations.classes) }
+      elsif @opts.export == :json
+        FileUtils.mkdir(@opts.output_dir)
+        init_output_dirs
+        @timer.time(:generating) { write_src(parsed_files) }
+        @timer.time(:generating) { format_classes }
+        @timer.time(:generating) { write_classes }
       else
-        if @template_links
-          link_template(@template_dir, @output_dir)
+        if @opts.template_links
+          link_template
         else
-          copy_template(@template_dir, @output_dir)
+          copy_template
+        end
+        create_template_html
+        create_print_template_html
+        if !@opts.seo
+          FileUtils.rm(@opts.output_dir+"/index.php")
+          FileUtils.cp(@opts.output_dir+"/template.html", @opts.output_dir+"/index.html")
         end
-        create_index_html(@template_dir, @output_dir)
-        @timer.time(:generating) { write_src(@output_dir+"/source", parsed_files) }
-        @timer.time(:generating) { write_tree(@output_dir+"/output/tree.js", relations) }
-        @timer.time(:generating) { write_search_data(@output_dir+"/output/searchData.js", relations) }
-        @timer.time(:generating) { write_classes(@output_dir+"/output", relations) }
-        @timer.time(:generating) { @guides.write(@output_dir+"/guides") }
+        @timer.time(:generating) { write_src(parsed_files) }
+        @timer.time(:generating) { format_classes }
+        @timer.time(:generating) { write_app_data }
+        @timer.time(:generating) { write_classes }
+        @timer.time(:generating) { @guides.write(@opts.output_dir+"/guides") }
+        @timer.time(:generating) { @videos.write(@opts.output_dir+"/videos") }
+        @timer.time(:generating) { @examples.write(@opts.output_dir+"/examples") }
       end
 
       @timer.report
@@ -154,7 +126,7 @@ module JsDuck
         agr.aggregate(file)
       end
       agr.classify_orphans
-      agr.create_global_class unless @ignore_global
+      agr.create_global_class unless @opts.ignore_global
       agr.append_ext4_event_options
       agr.result
     end
@@ -165,7 +137,7 @@ module JsDuck
       classes = []
       docs.each do |d|
         if d[:tagname] == :class
-          classes << Class.new(d) if !d[:private] || @show_private_classes
+          classes << Class.new(d)
         else
           type = d[:tagname].to_s
           name = d[:name]
@@ -174,69 +146,57 @@ module JsDuck
           Logger.instance.warn("Ignoring #{type}: #{name} in #{file} line #{line}")
         end
       end
-      Relations.new(classes, @external_classes)
+      Relations.new(classes, @opts.external_classes)
     end
 
-    # print warning for each global member
-    def warn_globals(relations)
-      global = relations["global"]
-      return unless global
-      global[:members].each_key do |type|
-        global.members(type).each do |member|
-          name = member[:name]
-          file = member[:filename]
-          line = member[:linenr]
-          Logger.instance.warn("Global #{type}: #{name} in #{file} line #{line}")
-        end
+    # Formats each class
+    def format_classes
+      formatter = ClassFormatter.new(@relations, get_doc_formatter)
+      # Don't format types when exporting
+      formatter.include_types = !@opts.export
+      # Format all doc-objects in parallel
+      formatted_docs = @parallel.map(@relations.classes) do |cls|
+        formatter.format(cls.internal_doc)
       end
-    end
-
-    # print warning for each member with no name
-    def warn_unnamed(relations)
-      relations.each do |cls|
-        cls[:members].each_pair do |type, members|
-          members.each do |member|
-            if !member[:name] || member[:name] == ""
-              file = member[:filename]
-              line = member[:linenr]
-              Logger.instance.warn("Unnamed #{type} in #{file} line #{line}")
-            end
-          end
-        end
+      # Then merge the data back to classes sequentially
+      formatted_docs.each do |doc|
+        @relations[doc[:name]].internal_doc = doc
       end
     end
 
-    # Given all classes, generates namespace tree and writes it
-    # in JSON form into a file.
-    def write_tree(filename, relations)
-      tree = Tree.new.create(relations.classes, @guides)
-      icons = TreeIcons.new.extract_icons(tree)
-      js = "Docs.classData = " + JSON.generate( tree ) + ";"
-      js += "Docs.icons = " + JSON.generate( icons ) + ";"
-      File.open(filename, 'w') {|f| f.write(js) }
+    # Writes classes, guides, videos, and search data to one big .js file
+    def write_app_data
+      js = "Docs.data = " + JsonDuck.generate({
+        :classes => Icons.new.create(@relations.classes),
+        :guides => @guides.to_array,
+        :videos => @videos.to_array,
+        :examples => @examples.to_array,
+        :search => SearchData.new.create(@relations.classes),
+      }) + ";\n"
+      File.open(@opts.output_dir+"/data.js", 'w') {|f| f.write(js) }
     end
 
-    # Given all classes, generates members data for search and writes in
-    # in JSON form into a file.
-    def write_search_data(filename, relations)
-      search_data = SearchData.new.create(relations.classes)
-      js = "Docs.searchData = " + JSON.generate( {:data => search_data} ) + ";"
-      File.open(filename, 'w') {|f| f.write(js) }
-    end
-
-    # Writes JsonP export file for each class
-    def write_classes(path, relations)
-      exporter = Exporter.new(relations, get_doc_formatter(relations))
-      @parallel.each(relations.classes) do |cls|
-        filename = path + "/" + cls[:name] + ".js"
+    # Writes JSON export or JsonP file for each class
+    def write_classes
+      exporter = Exporter.new(@relations)
+      renderer = Renderer.new
+      @parallel.each(@relations.classes) do |cls|
+        filename = @opts.output_dir+"/output/" + cls[:name] + (@opts.export ? ".json" : ".js")
         Logger.instance.log("Writing to #{filename} ...")
-        JsonP.write(filename, cls[:name].gsub(/\./, "_"), exporter.export(cls))
+        data = exporter.export(cls)
+        if @opts.export
+          JsonDuck.write_json(filename, data)
+        else
+          data[:html] = renderer.render(data)
+          data = exporter.compact(data)
+          JsonDuck.write_jsonp(filename, cls[:name].gsub(/\./, "_"), data)
+        end
       end
     end
 
     # Writes formatted HTML source code for each input file
-    def write_src(path, parsed_files)
-      src = SourceWriter.new(path, @export ? nil : :page)
+    def write_src(parsed_files)
+      src = SourceWriter.new(@opts.output_dir + "/source", @opts.export ? nil : :page)
       # Can't be done in parallel, because file.html_filename= method
       # updates all the doc-objects related to the file
       parsed_files.each do |file|
@@ -247,53 +207,76 @@ module JsDuck
     end
 
     # Creates and initializes DocFormatter
-    def get_doc_formatter(relations)
+    def get_doc_formatter
       formatter = DocFormatter.new
-      formatter.link_tpl = @link_tpl if @link_tpl
-      formatter.img_tpl = @img_tpl if @img_tpl
-      formatter.relations = relations
+      formatter.link_tpl = @opts.link_tpl if @opts.link_tpl
+      formatter.img_tpl = @opts.img_tpl if @opts.img_tpl
+      formatter.relations = @relations
+      if @opts.inline_examples_dir
+        formatter.get_example = lambda {|path| IO.read(@opts.inline_examples_dir + "/" + path) }
+      end
       formatter
     end
 
-    def copy_template(template_dir, dir)
-      Logger.instance.log("Copying template files to #{dir}...")
-      FileUtils.cp_r(template_dir, dir)
-      init_output_dirs(dir)
+    def copy_template
+      Logger.instance.log("Copying template files to #{@opts.output_dir}...")
+      FileUtils.cp_r(@opts.template_dir, @opts.output_dir)
+      init_output_dirs
     end
 
-    def link_template(template_dir, dir)
-      Logger.instance.log("Linking template files to #{dir}...")
-      FileUtils.mkdir(dir)
-      Dir.glob(template_dir + "/*").each do |file|
-        File.symlink(File.expand_path(file), dir+"/"+File.basename(file))
+    def link_template
+      Logger.instance.log("Linking template files to #{@opts.output_dir}...")
+      FileUtils.mkdir(@opts.output_dir)
+      Dir.glob(@opts.template_dir + "/*").each do |file|
+        File.symlink(File.expand_path(file), @opts.output_dir+"/"+File.basename(file))
       end
-      init_output_dirs(dir)
+      init_output_dirs
     end
 
-    def clear_dir(dir)
-      if File.exists?(dir)
-        FileUtils.rm_r(dir)
+    def clear_output_dir
+      if File.exists?(@opts.output_dir)
+        FileUtils.rm_r(@opts.output_dir)
       end
     end
 
-    def init_output_dirs(dir)
-      FileUtils.mkdir(dir + "/output")
-      FileUtils.mkdir(dir + "/source")
+    def init_output_dirs
+      FileUtils.mkdir(@opts.output_dir + "/output")
+      FileUtils.mkdir(@opts.output_dir + "/source")
+    end
+
+    def create_template_html
+      write_template("template.html", {
+        "{title}" => @opts.title,
+        "{header}" => @opts.header,
+        "{footer}" => "<div id='footer-content' style='display: none'>#{@opts.footer}</div>",
+        "{extjs_path}" => @opts.extjs_path,
+        "{local_storage_db}" => @opts.local_storage_db,
+        "{welcome}" => @welcome.to_html,
+        "{categories}" => @categories.to_html,
+        "{guides}" => @guides.to_html,
+        "{head_html}" => @opts.head_html,
+        "{body_html}" => @opts.body_html,
+      })
     end
 
-    def create_index_html(template_dir, dir)
-      Logger.instance.log("Creating #{dir}/index.html...")
-      html = IO.read(template_dir+"/index.html")
-      html.gsub!("{title}", @title)
-      html.gsub!("{footer}", "<div id='footer-content' style='display: none'>#{@footer}</div>")
-      html.gsub!("{extjs_path}", @extjs_path)
-      html.gsub!("{local_storage_db}", @local_storage_db)
-      html.gsub!("{guides}", @guides.to_html)
-      html.gsub!("{categories}", @categories.to_html)
-      html.gsub!("{head_html}", @head_html)
-      html.gsub!("{body_html}", @body_html)
-      FileUtils.rm(dir+"/index.html")
-      File.open(dir+"/index.html", 'w') {|f| f.write(html) }
+    def create_print_template_html
+      write_template("print-template.html", {
+        "{title}" => @opts.title,
+        "{header}" => @opts.header,
+      })
+    end
+
+    # Opens file in template dir, replaces {keys} inside it, writes to output dir
+    def write_template(filename, replacements)
+      in_file = @opts.template_dir + '/' + filename
+      out_file = @opts.output_dir + '/' + filename
+      Logger.instance.log("Creating #{out_file}...")
+      html = IO.read(in_file)
+      html.gsub!(/\{\w+\}/) do |key|
+        replacements[key] ? replacements[key] : key
+      end
+      FileUtils.rm(out_file)
+      File.open(out_file, 'w') {|f| f.write(html) }
     end
   end
 

data/lib/jsduck/categories.rb

@@ -1,5 +1,5 @@
 require 'jsduck/logger'
-require 'json'
+require 'jsduck/json_duck'
 
 module JsDuck
 
@@ -13,7 +13,22 @@ module JsDuck
 
     # Parses categories in JSON file
     def parse(path)
-      @categories = JSON.parse(IO.read(path))["categories"]
+      @categories = JsonDuck.read(path)["categories"]
+
+      # Perform expansion on all class names containing * wildcard
+      @categories.each do |cat|
+        cat["groups"].each do |group|
+          group["classes"] = group["classes"].map do |name|
+            expand(name) # name =~ /\*/ ? expand(name) : name
+          end.flatten
+        end
+      end
+    end
+
+    # Expands class name like 'Foo.*' into multiple class names.
+    def expand(name)
+      re = Regexp.new("^" + name.split(/\*/, -1).map {|part| Regexp.escape(part) }.join('.*') + "$")
+      @relations.to_a.find_all {|cls| re =~ cls[:name] && !cls[:private] }.map {|cls| cls[:name] }.sort
     end
 
     # Prints warnings for missing classes in categories file

data/lib/jsduck/class.rb

@@ -15,6 +15,16 @@ module JsDuck
       @relations = nil
     end
 
+    # Accessors for internal doc object.  These are used to run
+    # ClassFormatter on the internal doc object and then assign it
+    # back.
+    def internal_doc
+      @doc
+    end
+    def internal_doc=(doc)
+      @doc = doc
+    end
+
     def [](key)
       @doc[key]
     end

data/lib/jsduck/class_formatter.rb

@@ -0,0 +1,77 @@
+require 'jsduck/type_parser'
+require 'jsduck/logger'
+
+module JsDuck
+
+  # Converts :doc properties of class from markdown to HTML, resolves
+  # @links, and converts type definitions to HTML.  Also removes
+  # private members.
+  class ClassFormatter
+    # Set to false to disable HTML-formatting of type definitions.
+    attr_accessor :include_types
+
+    def initialize(relations, formatter)
+      @relations = relations
+      @formatter = formatter
+      @include_types = true
+    end
+
+    # Runs the formatter on doc object of a class.
+    # Accessed using Class#internal_doc
+    def format(cls)
+      @cls = cls
+      @formatter.class_context = cls[:name]
+      @formatter.doc_context = cls
+      cls[:doc] = @formatter.format(cls[:doc]) if cls[:doc]
+      cls[:members].each_pair do |type, members|
+        cls[:members][type] = members.reject {|m| m[:private] }.map {|m| format_member(m) }
+      end
+      cls[:statics].each_pair do |type, members|
+        cls[:statics][type] = members.reject {|m| m[:private] }.map {|m| format_member(m) }
+      end
+      cls
+    end
+
+    def format_member(m)
+      @formatter.doc_context = m
+      m[:doc] = @formatter.format(m[:doc]) if m[:doc]
+      m[:deprecated][:text] = @formatter.format(m[:deprecated][:text]) if m[:deprecated]
+      if expandable?(m) || @formatter.too_long?(m[:doc])
+        m[:shortDoc] = @formatter.shorten(m[:doc])
+      end
+      m[:html_type] = format_type(m[:type]) if m[:type] && @include_types
+      m[:params] = m[:params].map {|p| format_item(p) } if m[:params]
+      m[:return] = format_item(m[:return]) if m[:return]
+      m[:properties] = m[:properties].map {|b| format_item(b) } if m[:properties]
+      m
+    end
+
+    def expandable?(m)
+      m[:params] || (m[:properties] && m[:properties].length > 0) || m[:default] || m[:deprecated]
+    end
+
+    def format_item(it)
+      it[:doc] = @formatter.format(it[:doc]) if it[:doc]
+      it[:html_type] = format_type(it[:type]) if it[:type] && @include_types
+      it[:properties] = it[:properties].map {|s| format_item(s) } if it[:properties]
+      it
+    end
+
+    def format_type(type)
+      tp = TypeParser.new(@relations, @formatter)
+      if tp.parse(type)
+        tp.out
+      else
+        context = @formatter.doc_context
+        if tp.error == :syntax
+          Logger.instance.warn("Incorrect type syntax #{type} in #{context[:filename]} line #{context[:linenr]}")
+        else
+          Logger.instance.warn("Unknown type #{type} in #{context[:filename]} line #{context[:linenr]}")
+        end
+        type
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/doc_formatter.rb

@@ -29,6 +29,10 @@ module JsDuck
     # Default value: '<img src="%u" alt="%a"/>'
     attr_accessor :img_tpl
 
+    # Assign to this a function that retrieves the example code when
+    # passed in a filename
+    attr_accessor :get_example
+
     # Sets up instance to work in context of particular class, so
     # that when {@link #blah} is encountered it knows that
     # Context#blah is meant.
@@ -55,8 +59,11 @@ module JsDuck
       @relations = {}
       @link_tpl = '<a href="%c%#%m">%a</a>'
       @img_tpl = '<img src="%u" alt="%a"/>'
+      @example_tpl = '<pre class="inline-example"><code>%a</code></pre>'
       @link_re = /\{@link\s+(\S*?)(?:\s+(.+?))?\}/m
       @img_re = /\{@img\s+(\S*?)(?:\s+(.+?))?\}/m
+      @example_re = /\{@example\s+(\S*?)\s*\}/m
+      @example_annotation_re = /<pre><code>@example( +[^\n]*)?\s+/m
     end
 
     # Replaces {@link} and {@img} tags, auto-generates links for
@@ -67,6 +74,10 @@ module JsDuck
     #
     # Replaces {@img path/to/image.jpg Alt text} with HTML from @img_tpl.
     #
+    # Replaces {@example path/to/example.js} with source from that file.
+    #
+    # Adds 'inline-example' class to code examples beginning with @example.
+    #
     # Additionally replaces strings recognized as ClassNames with
     # links to these classes.  So one doesn even need to use the @link
     # tag to create a link.
@@ -78,10 +89,15 @@ module JsDuck
           out += replace_link_tag(s.scan(@link_re))
         elsif s.check(@img_re)
           out += replace_img_tag(s.scan(@img_re))
-        elsif s.check(/\{/)
-          out += s.scan(/\{/)
+        elsif s.check(@example_re)
+          out += replace_example_tag(s.scan(@example_re))
+        elsif s.check(@example_annotation_re)
+          s.scan(@example_annotation_re)
+          out += '<pre class="inline-example"><code>'
+        elsif s.check(/[{<]/)
+          out += s.scan(/[{<]/)
         else
-          out += replace_class_names(s.scan(/[^{]+/))
+          out += replace_class_names(s.scan(/[^{<]+/))
         end
       end
       out
@@ -128,6 +144,10 @@ module JsDuck
       input.sub(@img_re) { img($1, $2) }
     end
 
+    def replace_example_tag(input)
+      input.sub(@example_re) { example($1) }
+    end
+
     def replace_class_names(input)
       input.gsub(/(\A|\s)([A-Z][A-Za-z0-9.]*[A-Za-z0-9])(?:(#)([A-Za-z0-9]+))?([.,]?(?:\s|\Z))/m) do
         before = $1
@@ -136,7 +156,7 @@ module JsDuck
         member = $4
         after = $5
 
-        if @relations[cls] && (!member || get_member(cls, member))
+        if @relations[cls] && (member ? get_member(cls, member) : cls =~ /\./)
           label = member ? cls+"."+member : cls
           before + link(cls, member, label) + after
         else
@@ -159,6 +179,24 @@ module JsDuck
       end
     end
 
+    # Replaces example template with example read from file
+    def example(path)
+      @example_tpl.gsub(/(%\w)/) do
+        case $1
+        when '%a'
+          if @get_example
+            CGI.escapeHTML(@get_example.call(path))
+          else
+            file = @doc_context[:filename]
+            line = @doc_context[:linenr]
+            Logger.instance.warn("--examples not specified, but {@example} found in #{file} line #{line}.")
+          end
+        else
+          $1
+        end
+      end
+    end
+
     # applies the link template
     def link(cls, member, anchor_text, type=nil)
       # Use the canonical class name for link (not some alternateClassName)