Commit 494888d4 authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Support for @example annotation of code examples. 

Code examples beginning with @example are now automatically converted to
example components.  Like so:

    /**
     * See this example:
     *
     *     @example
     *     alert("This is a dynamic example");
     *
     * or this:
     *
     *     alert("That's a static example, no preview available");
     *
     */
parent 615f84a9

lib/jsduck/doc_formatter.rb

+12 −4
Original line number Diff line number Diff line
@@ -59,10 +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">%a</pre>'

      @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\s*\n/m

    end



    # Replaces {@link} and {@img} tags, auto-generates links for
@@ -73,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.
@@ -86,10 +91,13 @@ module JsDuck 
          out += replace_img_tag(s.scan(@img_re))

        elsif s.check(@example_re)

          out += replace_example_tag(s.scan(@example_re))

        elsif s.check(/\{/)

          out += s.scan(/\{/)

        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

spec/doc_formatter_spec.rb

+27 −2
Original line number Diff line number Diff line
@@ -118,13 +118,13 @@ describe JsDuck::DocFormatter do 
    it "replaces {@example foo.js} with source from foo.js file" do

      @formatter.get_example = lambda { "Some code" }

      @formatter.replace('{@example foo.js}').should ==

        '<pre class="inline-example">Some code</pre>'

        '<pre class="inline-example"><code>Some code</code></pre>'

    end



    it "escapes HTML inside source of {@example}" do

      @formatter.get_example = lambda { "Some <html> code" }

      @formatter.replace('{@example foo.js}').should ==

        '<pre class="inline-example">Some &lt;html&gt; code</pre>'

        '<pre class="inline-example"><code>Some &lt;html&gt; code</code></pre>'

    end



    # auto-conversion of identifiable ClassNames to links
@@ -301,6 +301,31 @@ describe JsDuck::DocFormatter do 
      end

    end



    describe "code block beginning with @example" do

      before do

        @html = @formatter.format(<<-EOS.gsub(/^ *\|/, ""))

          |See example:

          |

          |    @example

          |    if (condition) {

          |        doSomething();

          |    }

        EOS

      end



      it "creates <pre> with inline-example class" do

        @html.should =~ /<pre class="inline-example">/m

      end



      it "removes the line with @example markup" do

        @html.should_not =~ /@example/m

      end



      it "completely removes the first line" do

        @html.should =~ /code>if/m

      end

    end



  end



  describe "#shorten" do

template/app/controller/Examples.js

+1 −1
Original line number Diff line number Diff line
@@ -78,7 +78,7 @@ Ext.define('Docs.controller.Examples', { 
    replaceExampleDivs: function() {

        Ext.Array.each(Ext.query('.inline-example'), function(inlineEg) {

            // Grab code from <pre> element and replace it with new empty <div>

            var code = inlineEg.innerHTML;

            var code = inlineEg.innerText;

            var div = document.createElement("div");

            inlineEg.parentNode.replaceChild(div, inlineEg);

            // Then render the example component inside the div