docks_app 0.0.1

data/lib/docks/renderers/erb_renderer.rb

@@ -0,0 +1,68 @@
+require_relative "base_renderer.rb"
+require_relative "common_features/helperable.rb"
+require_relative "common_features/capturable.rb"
+
+module Docks
+  module Renderers
+    class ERB < Base
+      include Common::Helperable
+      include Common::Capturable
+
+      def initialize
+        require "erb"
+
+        super
+        @locals = []
+        @output = ""
+      end
+
+      def render(template, locals = {})
+        first_pass = @output.length < 1
+        final_output, @output = @output, ""
+
+        content, layout, locals = normalize_content_and_locals(template, locals)
+        return if content.nil?
+
+        @locals << locals
+        content = ::ERB.new(content, nil, nil, "@output").result(get_binding)
+        return content if layout.nil?
+
+        ::ERB.new(layout, nil, nil, "@output").result(get_binding { |name| name.nil? ? content : @content_blocks[name] })
+
+      ensure
+        @locals.pop
+        @output = first_pass ? "" : final_output
+      end
+
+      def get_binding
+        binding
+      end
+
+      def capture(*args, &block)
+        old_output, @output = @output, ""
+        yield *args
+        content = @output
+        @output = old_output
+        content
+      end
+
+      def concat(content)
+        @output << content
+      end
+
+      def method_missing(meth, *arguments, &block)
+        super if @locals.empty?
+        @locals.last.fetch(meth)
+      rescue KeyError
+        super
+      end
+
+      private
+
+      def clean
+        super
+        @locals = []
+      end
+    end
+  end
+end

data/lib/docks/renderers/haml_renderer.rb

@@ -0,0 +1,37 @@
+require_relative "base_renderer.rb"
+require_relative "common_features/helperable.rb"
+require_relative "common_features/capturable.rb"
+
+module Docks
+  module Renderers
+    class Haml < Base
+      include Common::Helperable
+      include Common::Capturable
+
+      def initialize
+        require "haml"
+        super
+      end
+
+      def render(template, locals = {})
+        old_buffer, @haml_buffer = @haml_buffer, nil
+
+        content, layout, locals = normalize_content_and_locals(template, locals)
+        return if content.nil?
+
+        content = ::Haml::Engine.new(content).render(binding, locals)
+        return content if layout.nil?
+
+        ::Haml::Engine.new(layout).render(binding, locals) do |name|
+          name.nil? ? content : @content_blocks[name]
+        end
+      ensure
+        @haml_buffer = old_buffer
+      end
+
+      def capture(*args, &block)
+        capture_haml(*args, &block)
+      end
+    end
+  end
+end

data/lib/docks/renderers/slim_renderer.rb

@@ -0,0 +1,33 @@
+require_relative "base_renderer.rb"
+require_relative "common_features/helperable.rb"
+require_relative "common_features/capturable.rb"
+
+module Docks
+  module Renderers
+    class Slim < Base
+      include Common::Helperable
+      include Common::Capturable
+
+      def initialize
+        require "slim"
+        super
+      end
+
+      def render(template, locals = {})
+        content, layout, locals = normalize_content_and_locals(template, locals)
+        return if content.nil?
+
+        content = ::Slim::Template.new { content }.render(self, locals)
+        return content if layout.nil?
+
+        ::Slim::Template.new { layout }.render(self, locals) do |name|
+          name.nil? ? content : @content_blocks[name]
+        end
+      end
+
+      def capture(*args, &block)
+        yield *args
+      end
+    end
+  end
+end

data/lib/docks/symbol_sources/base_symbol_source.rb

@@ -0,0 +1,12 @@
+require "singleton"
+
+module Docks
+  module SymbolSources
+    class Base
+      include Singleton
+
+      def recognizes?(symbol, options = {}); false end
+      def path_for(symbol); nil end
+    end
+  end
+end

data/lib/docks/symbol_sources/jquery_symbol_source.rb

@@ -0,0 +1,17 @@
+require_relative "base_symbol_source.rb"
+require_relative "../languages.rb"
+
+module Docks
+  module SymbolSources
+    class JQuery < Base
+      def recognizes?(symbol, options = {})
+        language = options.fetch(:language, nil)
+        return false if language && Languages.file_type(language) != Types::Languages::SCRIPT
+
+        symbol.downcase == "jquery"
+      end
+
+      def path_for(symbol); "http://api.jquery.com/" end
+    end
+  end
+end

data/lib/docks/symbol_sources/mdn_symbol_source.rb

@@ -0,0 +1,35 @@
+require_relative "base_symbol_source.rb"
+require_relative "../languages.rb"
+
+module Docks
+  module SymbolSources
+    class MDN < Base
+      GLOBAL_SYMBOLS = %w(
+        object function boolean symbol number date string regexp map set weakmap weakset arguments undefined
+        error evalerror internalerror rangeerror referenceerror syntaxerror typeerror urierror
+        array int8array uint8array uint8clampedarray int16array uint16array int32array uint32array float32array float64array
+        promise generator generatorfunction proxy iterator
+      )
+
+      WEB_API_SYMBOLS = %w(
+        abstractworker analysernode animationevent animationplayer apps.mgmt arraybufferview attr audiobuffer audiobuffersourcenode audiochannelmanager audiocontext audiodestinationnode audiolistener audionode audioparam audioprocessingevent batterymanager beforeinstallpromptevent beforeunloadevent biquadfilternode blob blobbuilder blobevent bluetoothadapter bluetoothdevice bluetoothdeviceevent bluetoothmanager bluetoothstatuschangedevent body broadcastchannel bytestring cdatasection css cssconditionrule csscounterstylerule cssgroupingrule csskeyframerule csskeyframesrule cssmatrix cssmediarule cssnamespacerule csspagerule cssrule cssrulelist cssstyledeclaration cssstylerule cssstylesheet csssupportsrule cache cachestorage callevent cameracapabilities cameracontrol cameramanager canvasgradient canvasimagesource canvaspattern canvasrenderingcontext2d caretposition channelmergernode channelsplitternode characterdata childnode chromeworker client clients clipboardevent closeevent comment compositionevent connection console contactmanager convolvernode coordinates crypto cryptokey customevent domapplication domapplicationsmanager domapplicationsregistry domconfiguration domcursor domerror domerrorhandler domexception domhighrestimestamp domimplementation domimplementationlist domimplementationregistry domimplementationsource domlocator dommatrix dommatrixreadonly domobject domparser dompoint dompointreadonly domrect domrectreadonly domrequest domstring domstringlist domstringmap domtimestamp domtokenlist domuserdata datastore datastorechangeevent datastorecursor datastoretask datatransfer dedicatedworkerglobalscope delaynode deviceacceleration devicelightevent devicemotionevent deviceorientationevent deviceproximityevent devicerotationrate devicestorage devicestoragechangeevent directoryentry directoryentrysync directoryreader directoryreadersync document documentfragment documenttouch documenttype dragevent dynamicscompressornode element elementtraversal encryptedmediaextensions api entity entityreference entry entrysync errorevent event eventlistener eventsource eventtarget extendableevent fmradio fetchevent file fileentry fileentrysync fileerror fileexception filehandle filelist filereader filereadersync filerequest filesystem filesystemsync focusevent formdata gainnode gamepad gamepadbutton gamepadevent geolocation globaleventhandlers globalfetch hmdvrdevice htmlanchorelement htmlareaelement htmlaudioelement htmlbrelement htmlbaseelement htmlbasefontelement htmlbodyelement htmlbuttonelement htmlcanvaselement htmlcollection htmlcontentelement htmldlistelement htmldataelement htmldatalistelement htmldialogelement htmldivelement htmldocument htmlelement htmlembedelement htmlfieldsetelement htmlformcontrolscollection htmlformelement htmlframesetelement htmlhrelement htmlheadelement htmlheadingelement htmlhtmlelement htmliframeelement htmlimageelement htmlinputelement htmlisindexelement htmlkeygenelement htmllielement htmllabelelement htmllegendelement htmllinkelement htmlmapelement htmlmediaelement htmlmetaelement htmlmeterelement htmlmodelement htmlolistelement htmlobjectelement htmloptgroupelement htmloptionelement htmloptionscollection htmloutputelement htmlparagraphelement htmlparamelement htmlpictureelement htmlpreelement htmlprogresselement htmlquoteelement htmlscriptelement htmlselectelement htmlshadowelement htmlsourceelement htmlspanelement htmlstyleelement htmltablecaptionelement htmltablecellelement htmltablecolelement htmltabledatacellelement htmltableelement htmltableheadercellelement htmltablerowelement htmltablesectionelement htmltextareaelement htmltimeelement htmltitleelement htmltrackelement htmlulistelement htmlunknownelement htmlvideoelement hashchangeevent headers history idbcursor idbcursorsync idbcursorwithvalue idbdatabase idbdatabaseexception idbdatabasesync idbenvironment idbenvironmentsync idbfactory idbfactorysync idbindex idbindexsync idbkeyrange idbobjectstore idbobjectstoresync idbopendbrequest idbrequest idbtransaction idbtransactionsync idbversionchangeevent idbversionchangerequest identitymanager imagedata index inputevent installevent keyboardevent l10n.formatvalue l10n.get l10n.language.code l10n.language.direction l10n.once l10n.ready l10n.readystate l10n.setattributes linkstyle localfilesystem localfilesystemsync localmediastream location lockedfile midiaccess midiconnectionevent midiinput midiinputmap mediadevices mediaelementaudiosourcenode mediakeymessageevent mediakeysession mediakeystatusmap mediakeysystemaccess mediakeysystemconfiguration mediakeys mediaquerylist mediaquerylistlistener mediarecorder mediasource mediastream mediastreamaudiodestinationnode mediastreamaudiosourcenode mediastreamevent mediastreamtrack messagechannel messageevent messageport mouseevent mousescrollevent mousewheelevent mozactivity mozactivityoptions mozactivityrequesthandler mozalarmsmanager mozcontact mozcontactchangeevent moziccmanager mozmmsevent mozmmsmessage mozmobilecfinfo mozmobilecellinfo mozmobileconnection mozmobileconnectioninfo mozmobileiccinfo mozmobilemessagemanager mozmobilemessagethread mozmobilenetworkinfo mozndefrecord moznfc moznfcpeer moznfctag moznetworkstats moznetworkstatsdata moznetworkstatsmanager mozsettingsevent mozsmsevent mozsmsfilter mozsmsmanager mozsmsmessage mozsmssegmentinfo mozsocial moztimemanager mozvoicemail mozvoicemailevent mozvoicemailstatus mozwificonnectioninfoevent mozwifip2pgroupowner mozwifip2pmanager mozwifistatuschangeevent mutationevent mutationobserver namelist namednodemap navigator navigatorgeolocation navigatorid navigatorlanguage navigatoronline navigatorplugins networkinformation node nodefilter nodeiterator nodelist nondocumenttypechildnode notation notification notifyaudioavailableevent offlineaudiocompletionevent offlineaudiocontext oscillatornode pagetransitionevent pannernode parentnode path2d performance performancenavigation performancetiming periodicsyncevent periodicsyncmanager periodicsyncregistration periodicwave permissionsettings permissionstatus permissions plugin pluginarray point popstateevent portcollection position positionerror positionoptions positionsensorvrdevice powermanager processinginstruction progressevent promiseresolver pushevent pushmanager pushsubscription rtcconfiguration rtcdatachannel rtcdatachannelevent rtcidentityerrorevent rtcidentityevent rtcpeerconnection rtcpeerconnectioniceevent rtcsessiondescription rtcsessiondescriptioncallback radionodelist randomsource range renderingcontext request response svgaelement svgangle svganimatecolorelement svganimateelement svganimatemotionelement svganimatetransformelement svganimatedangle svganimatedboolean svganimatedenumeration svganimatedinteger svganimatedlength svganimatedlengthlist svganimatednumber svganimatednumberlist svganimatedpoints svganimatedpreserveaspectratio svganimatedrect svganimatedstring svganimatedtransformlist svganimationelement svgcircleelement svgclippathelement svgcursorelement svgdefselement svgdescelement svgelement svgellipseelement svgevent svgfilterelement svgfontelement svgfontfaceelement svgfontfaceformatelement svgfontfacenameelement svgfontfacesrcelement svgfontfaceurielement svgforeignobjectelement svggelement svgglyphelement svggradientelement svghkernelement svgimageelement svglength svglengthlist svglineelement svglineargradientelement svgmpathelement svgmaskelement svgmatrix svgmissingglyphelement svgnumber svgnumberlist svgpathelement svgpatternelement svgpoint svgpolygonelement svgpolylineelement svgpreserveaspectratio svgradialgradientelement svgrect svgrectelement svgsvgelement svgscriptelement svgsetelement svgstopelement svgstringlist svgstylable svgstyleelement svgswitchelement svgsymbolelement svgtrefelement svgtspanelement svgtests svgtextelement svgtextpositioningelement svgtitleelement svgtransform svgtransformlist svgtransformable svguseelement svgvkernelement svgviewelement screen scriptprocessornode selection serviceworker serviceworkercontainer serviceworkerglobalscope serviceworkerregistration settingslock settingsmanager sharedworker sharedworkerglobalscope stereopannernode storage storageevent stylesheet stylesheetlist subtlecrypto syncevent syncmanager syncregistration tcpserversocket tcpsocket telephony telephonycall text textdecoder textencoder textmetrics timeevent timeranges touch touchevent touchlist transferable transitionevent treewalker typeinfo uievent url urlsearchparams urlutils urlutilsreadonly usvstring userdatahandler userproximityevent vrdevice vreyeparameters vrfieldofview vrfieldofviewreadonly vrpositionstate validitystate videoplaybackquality waveshapernode webglrenderingcontext websocket wheelevent wifimanager window windowbase64 windowclient windoweventhandlers windoweventhandlers.onbeforeprint windowtimers worker workerglobalscope workerlocation workernavigator xdomainrequest xmldocument xmlhttprequest xmlhttprequesteventtarget
+      )
+
+      GLOBAL_SYMBOL_URL = "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects"
+      WEB_API_SYMBOL_URL = "https://developer.mozilla.org/docs/Web/API"
+
+      def recognizes?(symbol, options = {})
+        language = options.fetch(:language, nil)
+        return false if language && Languages.file_type(language) != Types::Languages::SCRIPT
+
+        symbol = symbol.to_s.downcase
+        GLOBAL_SYMBOLS.include?(symbol) || WEB_API_SYMBOLS.include?(symbol)
+      end
+
+      def path_for(symbol)
+        return "#{GLOBAL_SYMBOL_URL}/#{symbol}" if GLOBAL_SYMBOLS.include?(symbol.downcase.to_s)
+        "#{WEB_API_SYMBOL_URL}/#{symbol}"
+      end
+    end
+  end
+end

data/lib/docks/symbol_sources/sass_symbol_source.rb

@@ -0,0 +1,27 @@
+require_relative "base_symbol_source.rb"
+require_relative "../languages.rb"
+require_relative "../languages/sass_language.rb"
+
+module Docks
+  module SymbolSources
+    class Sass < Base
+      VALUE_SYMBOLS = %w(arglist bool color list map null number string)
+
+      def recognizes?(symbol, options = {})
+        language = options.fetch(:language, nil)
+        return false if language && Languages.language_for(language) != Languages::Sass.instance
+
+        symbol = symbol.downcase
+        VALUE_SYMBOLS.include?(symbol) || symbol == "function"
+      end
+
+      def path_for(symbol)
+        if symbol.downcase == "function"
+          "http://sass-lang.com/documentation/Sass/Script/Script/Functions.html"
+        else
+          "http://sass-lang.com/documentation/Sass/Script/Value/#{symbol.capitalize}.html"
+        end
+      end
+    end
+  end
+end

data/lib/docks/symbol_sources.rb

@@ -0,0 +1,28 @@
+module Docks
+  module SymbolSources
+    @sources = []
+
+    def self.register(source)
+      source = source.instance
+      @sources << source unless @sources.include?(source)
+    end
+
+    def self.<<(source)
+      register(source)
+    end
+
+    def self.path_for(symbol, options = {})
+      @sources.each do |source|
+        return source.path_for(symbol) if source.recognizes?(symbol, options)
+      end
+
+      nil
+    end
+
+    private
+
+    def self.clear
+      @sources = []
+    end
+  end
+end

data/lib/docks/tags/access_tag.rb

@@ -0,0 +1,27 @@
+module Docks
+  module Types
+    module Access
+      PUBLIC      = "public"
+      PRIVATE     = "private"
+    end
+  end
+
+  module Tags
+    class Access < Base
+      def initialize
+        @name = :access
+        @multiline = false
+
+        @access_types = Docks::Types::Access.constants.map do |const|
+          Docks::Types::Access.const_get(const)
+        end
+      end
+
+      def process(symbol)
+        symbol.update(@name) do |access|
+          @access_types.include?(access) ? access : Docks::Types::Access::PUBLIC
+        end
+      end
+    end
+  end
+end

data/lib/docks/tags/activate_with_tag.rb

@@ -0,0 +1,17 @@
+module Docks
+  module Tags
+    class ActivateWith < Base
+      def initialize
+        @name = :activate_with
+        @multiline = false
+        @multiple_allowed = true
+      end
+
+      def process(symbol)
+        symbol.update(@name) do |activate_withs|
+          Array(activate_withs).map { |with| split_on_commas_spaces_and_pipes(with) }.flatten
+        end
+      end
+    end
+  end
+end

data/lib/docks/tags/active_tag.rb

@@ -0,0 +1,14 @@
+module Docks
+  module Tags
+    class Active < Base
+      def initialize
+        @name = :active
+        @multiline = false
+      end
+
+      def process(symbol)
+        symbol.update(@name) { |active| stringy_boolean(active) }
+      end
+    end
+  end
+end

data/lib/docks/tags/alias_tag.rb

@@ -0,0 +1,17 @@
+module Docks
+  module Tags
+    class Alias < Base
+      def initialize
+        @name = :alias
+        @multiline = false
+        @multiple_allowed = true
+      end
+
+      def process(symbol)
+        symbol.update(@name) do |aliases|
+          Array(aliases).map { |alias_line| split_on_commas_spaces_and_pipes(alias_line) }.flatten
+        end
+      end
+    end
+  end
+end

data/lib/docks/tags/author_tag.rb

@@ -0,0 +1,19 @@
+module Docks
+  module Tags
+    class Author < Base
+      def initialize
+        @name = :author
+        @synonyms = [:contributor]
+        @multiple_allowed = true
+        @multiline = false
+      end
+
+      def process(symbol)
+        symbol.update(@name) do |authors|
+          authors = Array(authors).map { |author| split_on_top_level_parens_commas_and_pipes(author) }.flatten
+          authors.map { |author| OpenStruct.new name_and_parenthetical(author, :name, :email) }
+        end
+      end
+    end
+  end
+end

data/lib/docks/tags/base_tag.rb

@@ -0,0 +1,52 @@
+require_relative "../processors.rb"
+
+module Docks
+  module Tags
+
+    # Public: The base tag from which bundled and custom tags can inherit.
+
+    class Base
+      include Singleton
+      include Processors
+
+      attr_reader :name
+
+      def multiline?
+        @multiline = true if @multiline.nil?
+        @multiline
+      end
+
+      def multiple_allowed?
+        @multiple_allowed = false if @multiple_allowed.nil?
+        @multiple_allowed
+      end
+
+      def type
+        @type ||= Docks::Types::Tags::ONE_PER_BLOCK
+      end
+
+      def parseable?
+        @parseable = true if @parseable.nil?
+        @parseable
+      end
+
+      def synonyms
+        @synonyms ||= []
+      end
+
+      def process(symbol); symbol end
+
+      def setup_post_processors; end
+
+      protected
+
+      def after_each_pattern(hook = nil, &block)
+        Process.register_pattern_processor(hook, &block)
+      end
+
+      def after_all(hook = nil, &block)
+        Process.register_pattern_library_processor(hook, &block)
+      end
+    end
+  end
+end

data/lib/docks/tags/beta_tag.rb

@@ -0,0 +1,26 @@
+module Docks
+  module Tags
+    class Beta < Base
+      def initialize
+        @name = :beta
+        @synonyms = [:experimental]
+      end
+
+      def process(symbol)
+        symbol.update(@name) do |beta|
+          beta = multiline_description(beta) do |first_line|
+            if match = first_line.match(/\s*(?<version>.*?)(?:\s+\-\s+(?<description>.*))?$/)
+              description = match[:description]
+              {
+                version: match[:version],
+                description: description.nil? || description.length == 0 ? nil : match[:description]
+              }
+            end
+          end
+
+          OpenStruct.new(beta)
+        end
+      end
+    end
+  end
+end

data/lib/docks/tags/class_tag.rb

@@ -0,0 +1,16 @@
+module Docks
+  module Tags
+    class Klass < Base
+      def initialize
+        @name = :class
+        @multiline = false
+      end
+
+      def process(symbol)
+        symbol.symbol_type = Types::Symbol::CLASS
+        symbol[@name] = true
+        Containers::Klass.from_symbol(symbol)
+      end
+    end
+  end
+end

data/lib/docks/tags/compatibility_tag.rb

@@ -0,0 +1,19 @@
+module Docks
+  module Tags
+    class Compatibility < Base
+      def initialize
+        @name = :compatibility
+        @synonyms = [:compatible_with, :support]
+        @multiline = false
+        @multiple_allowed = true
+      end
+
+      def process(symbol)
+        symbol.update(@name) do |compatibilities|
+          compatibilities = Array(compatibilities).map { |compatibility| split_on_top_level_parens_commas_and_pipes(compatibility) }.flatten
+          compatibilities.map { |compatibility| OpenStruct.new name_and_parenthetical(compatibility, :browser, :version) }
+        end
+      end
+    end
+  end
+end

data/lib/docks/tags/demo_type_tag.rb

@@ -0,0 +1,14 @@
+module Docks
+  module Tags
+    class DemoType < Base
+      def initialize
+        @name = :demo_type
+        @multiline = false
+      end
+
+      def process(symbol)
+        symbol.update(@name) { |demo_type| ensure_valid_demo_type(demo_type) }
+      end
+    end
+  end
+end

data/lib/docks/tags/deprecated_tag.rb

@@ -0,0 +1,26 @@
+module Docks
+  module Tags
+    class Deprecated < Base
+      def initialize
+        @name = :deprecated
+        @synonyms = [:deprecation]
+      end
+
+      def process(symbol)
+        symbol.update(@name) do |deprecated|
+          deprecated = multiline_description(deprecated) do |first_line|
+            if match = first_line.match(/\s*(?<version>.*?)(?:\s+\-\s+(?<description>.*))?$/)
+              description = match[:description]
+              {
+                version: match[:version],
+                description: description.nil? || description.length == 0 ? nil : match[:description]
+              }
+            end
+          end
+
+          OpenStruct.new(deprecated)
+        end
+      end
+    end
+  end
+end

data/lib/docks/tags/description_tag.rb

@@ -0,0 +1,99 @@
+require "redcarpet"
+require_relative "../markdown.rb"
+
+module Docks
+  module Tags
+    class Description < Base
+      def initialize
+        @name = :description
+        @markdown = Redcarpet::Markdown.new(Markdown::Renderer, fenced_code_blocks: true)
+      end
+
+      def process(symbol)
+        symbol.update(@name) { |description| join_with_smart_line_breaks(description) }
+      end
+
+      def setup_post_processors
+        after_each_pattern(:late) do |pattern|
+          associate_external_description_files(pattern)
+          recursive_markdown_description(pattern)
+          pattern.symbols.each { |symbol| recursive_markdown_description(symbol) }
+        end
+      end
+
+      protected
+
+      def recursive_markdown_description(symbol)
+        return unless symbol.respond_to?(:description)
+        description = symbol.description
+
+        if description.nil? || description.strip.empty?
+          symbol.description = nil
+        else
+          symbol.description = @markdown.render(description)
+        end
+
+        return unless symbol.respond_to?(:each)
+        symbol.each do |tag, value|
+          if value.kind_of?(Array)
+            value.each { |item| recursive_markdown_description(item) }
+          else
+            recursive_markdown_description(value)
+          end
+        end
+
+        if symbol.respond_to?(:members)
+          symbol.members.each { |member| recursive_markdown_description(member) }
+        end
+      end
+
+      def associate_external_description_files(pattern)
+        description_file = pattern.files.find { |file| Languages.file_type(file) == Types::Languages::DESCRIPTION }
+        return if description_file.nil?
+
+        description = File.read(description_file)
+        remaining_description = slice_up_description_for_symbols(description, pattern.symbols)
+        pattern.description ||= remaining_description
+      end
+
+      def smart_description_association(symbol, description)
+        case symbol
+        when Containers::Component
+          remaining_description = slice_up_description_for_symbols(description, symbol.fetch(:states, []) + symbol.fetch(:variants, []))
+          symbol.description ||= remaining_description
+
+        when Containers::Function
+          remaining_description = slice_up_description_for_symbols(description, symbol.fetch(:params, []) + symbol.members)
+          symbol.description ||= remaining_description
+
+        when Containers::Symbol
+          remaining_description = slice_up_description_for_symbols(description, symbol.members)
+          symbol.description ||= remaining_description
+
+        else
+          symbol.description = description
+        end
+      end
+
+      def slice_up_description_for_symbols(description, symbols)
+        earliest_other_description_start = description.length
+
+        symbols.each do |symbol|
+          next unless symbol.description.nil?
+
+          regex = Regexp.new("^(#+)\\s*#{Regexp.escape(symbol.name)}\\s*$", Regexp::MULTILINE)
+          if match = regex.match(description)
+            next_matched_heading = Regexp.new("^#\{1,#{match[1].length}} [^#]", Regexp::MULTILINE).match(description, match.offset(1)[1])
+            next_matched_heading_position = next_matched_heading.nil? ? description.length : next_matched_heading.offset(0)[0] - 1
+
+            description_range = match.offset(0)[1]..next_matched_heading_position
+            smart_description_association(symbol, description[description_range].strip)
+            earliest_other_description_start = [earliest_other_description_start, description_range.first - match[0].length - 1].min
+          end
+        end
+
+        description[0..earliest_other_description_start].strip
+      end
+    end
+  end
+end

data/lib/docks/tags/example_tag.rb

@@ -0,0 +1,20 @@
+module Docks
+  module Tags
+    class Example < Base
+      def initialize
+        @name = :example
+        @multiple_allowed = true
+      end
+
+      def process(symbol)
+        symbol.update(@name) do |examples|
+          examples.map do |example|
+            example = code_block_with_language_and_description(example)
+            example[:language] ||= Docks::Languages.extension_for_file(Docks.current_file)
+            OpenStruct.new(example)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docks/tags/factory_tag.rb

@@ -0,0 +1,16 @@
+module Docks
+  module Tags
+    class Factory < Base
+      def initialize
+        @name = :factory
+        @multiline = false
+      end
+
+      def process(symbol)
+        symbol[@name] = true
+        symbol.symbol_type = Types::Symbol::FACTORY
+        Containers::Factory.from_symbol(symbol)
+      end
+    end
+  end
+end