Multi line tags

Continuing with our @license tag example, lets turn it into a multi-line tag, so we can also include the actual license text:

/**
 * @class My.Class
 * An example class.
 *
 * @license GNU General Public License v3
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * [GNU General Public License](http://www.gnu.org/licenses/gpl.html)
 * for more details.
 *
 * @license MIT License
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use, copy,
 * modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 */

So we want to treat the text on the same line as @license tag as the name of the license and grab the text on all the following lines as the content. We already implemented getting the first line in the single-line tags tutorial, with just a few modifications we can alse extract all the following lines:

require "jsduck/tag/tag"

class License < JsDuck::Tag::Tag
  def initialize
    @tagname = :license
    @pattern = "license"
    @html_position = POS_DOC + 0.1
    @repeatable = true
  end

  def parse_doc(scanner, position)
    name = scanner.match(/.*$/)
    return { :tagname => :license, :name => name, :doc => :multiline }
  end

  def process_doc(context, license_tags, position)
    context[:license] = license_tags
  end

  def to_html(context)
    context[:license].map do |license|
      <<-EOHTML
        <h2>#{license[:name]}</h2>
        #{license[:doc]}
      EOHTML
    end.join
  end
end

Notice the return value of parse_doc method:

return { :tagname => :license, :name => name, :doc => :multiline }

In addition to :tagname and :name fields we add a special :doc => :multiline field. This tells JSDuck to take all the text up to the next @tag and place it inside :doc field.

In process_doc we just assign the whole array of license tag data to context hash field.

Finally in to_html we turn :name into a header and include :doc as the content.

Here's the result:

It works, yeah, but all our paragraphs are smashed together and the Markdown link to GNU site is treated as plain text.

Guess we didn't say to JSDuck we want our content to be treated as Markdown. Jump to next chapter to see how it's done.