kramdown-asciidoc 1.0.0.alpha.13 → 1.0.0.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f703fb6eabd74ef5641f298a7d7bc2fadce80e5fe9b97d1965abad29a5f5a4d6
-  data.tar.gz: 18c3c1f8f4f2006381b83561badf425e56762216c92d64cc42aae640058ded82
+  metadata.gz: fbe551c7f58e65076b32bccc18a15c31d4ad2f7a6e7510ff37095e1782d0bd90
+  data.tar.gz: 1bbf3ccce901f2b9dd470a09a9f54fe257461922cbb1ef959cbc9071a3d72bca
 SHA512:
-  metadata.gz: 1f51c28d5cfa7d9c7fb8c1f32e5502a052b0e0030f782c0f4e4f6814c792a36d9f9e03663013d84b338021e0524fefb0fcf54b8a381078f22ebb56cd1f645f06
-  data.tar.gz: 768357f79d874791c79aa6f4a0c1df5f3eaa3fff1648b03f1465d5648ba64ab62279823a2e9133950e42904fdb75c84462db830a1ceecfc2e50d1d60f6b7fafe
+  metadata.gz: e1ee0ea89e5769051d486a231f15f1c9e6ad0ad7e8a1094573d4cf2fa994b8c2a581db49b65486b188101c16dbf16ce05f032ca17d598cd360cfbaf1c243bcbb
+  data.tar.gz: '0381ac4bade1dc05edcc5825e3acbc4074ef9ed692ea8074e7eab89d69f20074c06478d4bd9407441263a261b0a132a0e385d2798f551a62529cc57bc149ec89'

data/CHANGELOG.adoc

@@ -5,6 +5,26 @@
 This document provides a high-level view of the changes to {project-name} by release.
 For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
 
+== 1.0.0.rc.1 (2018-11-06) - @mojavelinux
+
+=== Added
+
+* ventilate prose on semi-colon following non-space character
+* add :preprocessors option to convert API; apply default preprocessors if not set; apply none if falsy (#23)
+* add :postprocessors option to convert API; takes precedence over :postprocess option (#67)
+* accept IO object as input to convert method (#49)
+* accept File object as input to convert_file method (#49)
+* add API docs to public API methods
+
+=== Changed
+
+* remove whitespace in front of leading XML comment (so a block comment isn't mistaken for an inline comment)
+* drop empty XML comment unless it comes after a list
+
+=== Details
+
+{uri-repo}/releases/tag/v1.0.0.rc.1[git tag] | {uri-repo}/compare/v1.0.0.alpha.13\...v1.0.0.rc.1[full diff]
+
 == 1.0.0.alpha.13 (2018-08-21) - @mojavelinux
 
 === Added
@@ -25,6 +45,10 @@ For a detailed view of what has changed, refer to the {uri-repo}/commits/master[
 
 * enclose codeblock content in literal block delimiters if content starts with a list marker (#57)
 
+=== Details
+
+{uri-repo}/releases/tag/v1.0.0.alpha.13[git tag] | {uri-repo}/compare/v1.0.0.alpha.12\...v1.0.0.alpha.13[full diff]
+
 == 1.0.0.alpha.12 (2018-08-11) - @mojavelinux
 
 === Added

data/Gemfile

@@ -1,3 +1,8 @@
 source 'https://rubygems.org'
 
 gemspec
+
+group :docs do
+  gem 'yard'
+  gem 'asciidoctor'
+end

data/README.adoc

@@ -1,6 +1,6 @@
 = {project-name} (Markdown to AsciiDoc)
 Dan Allen <https://github.com/mojavelinux>
-v1.0.0.alpha.13, 2018-08-21
+v1.0.0.rc.1, 2018-11-06
 // Aliases:
 :project-name: Kramdown AsciiDoc
 :project-handle: kramdown-asciidoc
@@ -25,26 +25,26 @@ endif::[]
 :uri-kramdown: https://kramdown.gettalong.org
 :uri-rvm: https://rvm.io
 :uri-rvm-install: https://rvm.io/rvm/install
-:uri-docs-api: https://www.rubydoc.info/github/asciidoctor/kramdown-asciidoc/master
+:uri-api-docs: https://www.rubydoc.info/github/asciidoctor/kramdown-asciidoc/master
 :uri-ci-appveyor: https://ci.appveyor.com/project/asciidoctor/kramdown-asciidoc
-:img-ci-appveyor: https://ci.appveyor.com/api/projects/status/2pwvdbcoeux1ifb5/branch/master?svg=true
+:img-uri-ci-appveyor: https://ci.appveyor.com/api/projects/status/2pwvdbcoeux1ifb5/branch/master?svg=true
 :uri-ci-travis: https://travis-ci.org/asciidoctor/kramdown-asciidoc
-:uri-ci-travis-img: https://img.shields.io/travis/asciidoctor/kramdown-asciidoc/master.svg
+:img-uri-ci-travis: https://img.shields.io/travis/asciidoctor/kramdown-asciidoc/master.svg
 :uri-gem: https://rubygems.org/gems/kramdown-asciidoc
-:uri-gem-img: https://img.shields.io/gem/v/kramdown-asciidoc.svg?label=gem
+:img-uri-gem: https://img.shields.io/gem/v/kramdown-asciidoc.svg?label=gem
 
 ifdef::status[]
-image:{uri-gem-img}[Gem Version,link={uri-gem}]
-image:{uri-ci-travis-img}[Build Status (Travis CI),link={uri-ci-travis}]
-image:{img-ci-appveyor}[Build Status (AppVeyor),link={uri-ci-appveyor}]
+image:{img-uri-gem}[Gem Version,link={uri-gem}]
+image:{img-uri-ci-travis}[Build Status (Travis CI),link={uri-ci-travis}]
+image:{img-uri-ci-appveyor}[Build Status (AppVeyor),link={uri-ci-appveyor}]
 endif::[]
 
-{uri-repo}[{project-name}] (gem: *{project-handle}*) is a {uri-kramdown}[kramdown] extension for converting Markdown documents to {uri-asciidoc}[AsciiDoc].
+{uri-repo}[{project-name}] (gem: *{project-handle}*, command: `kramdoc`) is a {uri-kramdown}[kramdown] extension for converting Markdown documents to {uri-asciidoc}[AsciiDoc].
 Notably, the converter generates modern AsciiDoc syntax suitable for use with {uri-asciidoctor}[Asciidoctor].
 
 == Prerequisites
 
-To install and run {project-name}, you need Ruby 2.4 or better installed and a few RubyGems (aka gems).
+To install and run {project-name}, you need Ruby 2.3 or better installed and a few RubyGems (aka gems).
 We'll explain how to install the gems in the next section.
 
 To check whether you have Ruby installed, and which version, run the following command:
@@ -164,15 +164,15 @@ If these values do not match the defaults in AsciiDoc, the `idprefix` and/or `id
 
 == API
 
-In additional to the command-line interface, {project-name} also provides a porcelain API (see {uri-docs-api}[API docs]).
+In additional to the command-line interface, {project-name} also provides a porcelain API (see {uri-api-docs}[API docs]).
 We use the term "`porcelain`" because the API hides the details of registering the converter, preprocessing the Markdown document, parsing the document with kramdown, and calling the converter method to transform the parse tree to AsciiDoc.
 
-The API consists of two static methods:
+The API consists of two static methods in the Kramdoc module:
 
-* `Kramdoc.convert(source, opts)` - convert a Markdown string to AsciiDoc
-* `Kramdoc.convert_file(file, opts)` - convert a Markdown file to AsciiDoc
+* `Kramdoc.convert(source, opts)` - convert a Markdown string or IO object to AsciiDoc
+* `Kramdoc.convert_file(file, opts)` - convert a Markdown file object or path to AsciiDoc
 
-NOTE: `Kramdoc` is shorthand for `Kramdown::AsciiDoc` to align with the name of the CLI.
+NOTE: `Kramdoc` is a shorthand for `Kramdown::AsciiDoc` to align with the name of the CLI.
 
 Both API methods accept the source as the first argument and an options hash as the second.
 
@@ -220,7 +220,7 @@ Kramdoc.convert markdown, to: 'result.adoc'
 
 The input string is automatically converted to UTF-8.
 
-For more information about the API, refer to the {uri-docs-api}[API documentation].
+For more information about the API, refer to the {uri-api-docs}[API documentation].
 
 == Development
 

data/kramdown-asciidoc.gemspec

@@ -17,23 +17,21 @@ Gem::Specification.new do |s|
     'mailing_list_uri' => 'http://discuss.asciidoctor.org',
     'source_code_uri' => 'https://github.com/asciidoctor/kramdown-asciidoc'
   }
-  #s.required_ruby_version = '>= 2.4.0'
+  # NOTE required ruby version is informational only; it's not enforced since it can't be overridden and can cause builds to break
+  #s.required_ruby_version = '>= 2.3.0'
 
   files = begin
     (result = Open3.popen3('git ls-files -z') {|_, out| out.read }.split ?\0).empty? ? Dir['**/*'] : result
   rescue
     Dir['**/*']
   end
-  s.files = files.grep %r/^(?:lib\/.+|Gemfile|Rakefile|(?:CHANGELOG|CONTRIBUTING|LICENSE|README)\.adoc|#{s.name}\.gemspec)$/
-  s.test_files = files.grep %r/^(?:spec\/.+)$/
+  #s.files = files.grep %r/^(?:lib\/.+|Gemfile|Rakefile|(?:CHANGELOG|CONTRIBUTING|LICENSE|README)\.adoc|#{s.name}\.gemspec)$/
+  #s.test_files = files.grep %r/^(?:spec\/.+)$/
+  s.files = files.grep %r/^(?:lib\/.+|Gemfile|(?:CHANGELOG|LICENSE|README)\.adoc|#{s.name}\.gemspec)$/
   s.executables = ['kramdoc']
 
   s.require_paths = ['lib']
 
-  #s.has_rdoc = true
-  #s.rdoc_options = ['--charset=UTF-8']
-  #s.extra_rdoc_files = ['CHANGELOG.adoc', 'LICENSE.adoc']
-
   s.add_runtime_dependency 'kramdown', '~> 1.17.0'
   s.add_development_dependency 'deep-cover-core', '~> 0.6.3'
   s.add_development_dependency 'rake', '~> 12.3.1'

data/lib/kramdown-asciidoc.rb

@@ -2,8 +2,13 @@ require 'kramdown'
 require_relative 'kramdown-asciidoc/kramdown_ext/parser/base'
 require_relative 'kramdown-asciidoc/kramdown_ext/parser/html'
 require_relative 'kramdown-asciidoc/core_ext/regexp/is_match'
-require_relative 'kramdown-asciidoc/api'
-require_relative 'kramdown-asciidoc/converter'
+require_relative 'kramdown-asciidoc/preprocessors'
 require_relative 'kramdown-asciidoc/writer'
+require_relative 'kramdown-asciidoc/converter'
+require_relative 'kramdown-asciidoc/api'
+# register AsciiDoc converter with kramdown
+Kramdown::Converter::Asciidoc = Kramdown::AsciiDoc::Converter
+# add Kramdoc alias
+Kramdoc = Kramdown::AsciiDoc
 autoload :Pathname, 'pathname'
 autoload :YAML, 'yaml'

data/lib/kramdown-asciidoc/api.rb

@@ -1,21 +1,57 @@
 module Kramdown; module AsciiDoc
-  CR = ?\r
-  LF = ?\n
-  UTF_8 = ::Encoding::UTF_8
+  DEFAULT_PARSER_OPTS = {
+    auto_ids: false,
+    hard_wrap: false,
+    html_to_native: true,
+    input: 'GFM',
+  }
 
+  DEFAULT_PREPROCESSORS = [
+    (Preprocessors.method :extract_front_matter),
+    (Preprocessors.method :replace_toc),
+    (Preprocessors.method :snap_leading_comment),
+  ]
+
+  # Converts a Markdown string to an AsciiDoc string and either returns the result or writes it to a file.
+  #
+  # @param markdown [String, IO] the Markdown source to convert to AsciiDoc.
+  # @param opts [Hash] additional options to configure the behavior of the converter.
+  # @option opts [Boolean] :auto_ids (false) controls whether converter automatically generates an explicit ID for any
+  #   section title (aka heading) that doesn't already have an ID assigned to it.
+  # @option opts [String] :auto_id_prefix (nil) the prefix to add to an auto-generated ID.
+  # @option opts [String] :auto_id_separator ('-') the separator to use in auto-generated IDs.
+  # @option opts [Boolean] :lazy_ids (false) controls whether to drop the ID if it matches the auto-generated ID value.
+  # @option opts [Symbol] :wrap (:preserve) the line wrapping behavior to apply (:preserve, :ventilate, or :none).
+  # @option opts [Integer] :heading_offset (0) the heading offset to apply to heading levels.
+  # @option opts [Boolean] :auto_links (true) whether to allow raw URLs to be recognized as links.
+  # @option opts [Hash] :attributes ({}) AsciiDoc attributes to add to the document header of the output document.
+  # @option opts [Symbol] :encode (true) whether to reencode the source to UTF-8.
+  # @option opts [Array<Proc>] :preprocessors ([]) a list of preprocessors functions to execute on the cleaned Markdown source.
+  # @option opts [Array<Proc>] :postprocessors ([]) a list of functions through which to run the output document.
+  # @option opts [Proc] :postprocess (nil) a function through which to run the output document (if :postprocessors is falsy).
+  # @option opts [String, Pathname] :to (nil) the path to which to write the output document.
+  #
+  # @return [String, nil] the converted AsciiDoc or nil if the :to option is specified.
   def self.convert markdown, opts = {}
-    unless opts[:encode] == false || (markdown.encoding == UTF_8 && !(markdown.include? CR))
+    if markdown.respond_to? :read
+      markdown = markdown.read
+      encode = true
+    else
+      encode = opts[:encode]
+    end
+    unless encode == false || (markdown.encoding == UTF_8 && !(markdown.include? CR))
       markdown = markdown.encode UTF_8, universal_newline: true
     end
     markdown = markdown.rstrip
     markdown = markdown.slice 1, markdown.length while markdown.start_with? LF
-    parser_opts = ::Kramdown::AsciiDoc::DEFAULT_PARSER_OPTS.merge opts
+    parser_opts = DEFAULT_PARSER_OPTS.merge opts
     attributes = (parser_opts[:attributes] = (parser_opts[:attributes] || {}).dup)
-    markdown = ::Kramdown::AsciiDoc.extract_front_matter markdown, attributes
-    markdown = ::Kramdown::AsciiDoc.replace_toc markdown, attributes
+    ((opts.fetch :preprocessors, DEFAULT_PREPROCESSORS) || []).each do |preprocessor|
+      markdown = preprocessor[markdown, attributes]
+    end
     asciidoc = (kramdown_doc = ::Kramdown::Document.new markdown, parser_opts).to_asciidoc
-    if (postprocess = opts[:postprocess])
-      asciidoc = (postprocess.arity == 1 ? postprocess[asciidoc] : postprocess[asciidoc, kramdown_doc]) || asciidoc
+    (opts[:postprocessors] || Array(opts[:postprocess])).each do |postprocessor|
+      asciidoc = (postprocessor.arity == 1 ? postprocessor[asciidoc] : postprocessor[asciidoc, kramdown_doc]) || asciidoc
     end
     asciidoc += LF unless asciidoc.empty?
     if (to = opts[:to])
@@ -31,18 +67,47 @@ module Kramdown; module AsciiDoc
     end
   end
 
+  # Converts a Markdown file to AsciiDoc and writes the result to a file or the specified destination.
+  #
+  # @param markdown_file [String, File] the Markdown file or file path to convert to AsciiDoc.
+  # @param opts [Hash] additional options to configure the behavior of the converter.
+  # @option opts [Boolean] :auto_ids (false) controls whether converter automatically generates an explicit ID for any
+  #   section title (aka heading) that doesn't already have an ID assigned to it.
+  # @option opts [String] :auto_id_prefix (nil) the prefix to add to an auto-generated ID.
+  # @option opts [String] :auto_id_separator ('-') the separator to use in auto-generated IDs.
+  # @option opts [Boolean] :lazy_ids (false) controls whether to drop the ID if it matches the auto-generated ID value.
+  # @option opts [Symbol] :wrap (:preserve) the line wrapping behavior to apply (:preserve, :ventilate, or :none).
+  # @option opts [Integer] :heading_offset (0) the heading offset to apply to heading levels.
+  # @option opts [Boolean] :auto_links (true) whether to allow raw URLs to be recognized as links.
+  # @option opts [Hash] :attributes ({}) AsciiDoc attributes to add to the document header of the output document.
+  # @option opts [Array<Proc>] :preprocessors ([]) a list of preprocessors functions to execute on the cleaned Markdown source.
+  # @option opts [Array<Proc>] :postprocessors ([]) a list of functions through which to run the output document.
+  # @option opts [Proc] :postprocess (nil) a function through which to run the output document (if :postprocessors is falsy).
+  # @option opts [String, Pathname] :to (nil) the path to which to write the output document.
+  #
+  # @return [String, nil] the converted document if the :to option is specified and is falsy, otherwise nil.
   def self.convert_file markdown_file, opts = {}
-    markdown = ::IO.read markdown_file, mode: 'r:UTF-8', newline: :universal
+    if ::File === markdown_file
+      markdown = markdown_file.read
+      markdown_file = markdown_file.path
+      encode = true
+    else
+      markdown = ::IO.read markdown_file, mode: 'r:UTF-8', newline: :universal
+      encode = false
+    end
     if (to = opts[:to])
       to = ::Pathname.new to.to_s unless ::Pathname === to || (to.respond_to? :write)
-    else
-      unless opts.key? :to
-        to = (::Pathname.new markdown_file).sub_ext '.adoc'
-        raise ::IOError, %(input and output cannot be the same file: #{markdown_file}) if to.to_s == markdown_file.to_s
-      end
+    elsif !(opts.key? :to)
+      to = (::Pathname.new markdown_file).sub_ext '.adoc'
+      raise ::IOError, %(input and output cannot be the same file: #{markdown_file}) if to.to_s == markdown_file.to_s
     end
-    convert markdown, (opts.merge to: to, encode: false)
+    convert markdown, (opts.merge to: to, encode: encode)
   end
-end; end
 
-Kramdoc = Kramdown::AsciiDoc
+  private
+
+  CR = ?\r
+  LF = ?\n
+  TAB = ?\t
+  UTF_8 = ::Encoding::UTF_8
+end; end

data/lib/kramdown-asciidoc/cli.rb

@@ -109,7 +109,7 @@ module Kramdown; module AsciiDoc
       pipe_out = (output_file = options.delete :output_file) == '-'
       if pipe_in
         options[:to] = pipe_out || !output_file ? $stdout : output_file
-        ::Kramdoc.convert $stdin.read, options
+        ::Kramdoc.convert $stdin, options
       elsif output_file && !pipe_out && (::File.expand_path input_file) == (::File.expand_path output_file)
         $stderr.write %(kramdoc: input and output cannot be the same file: #{input_file}\n)
         return 1

data/lib/kramdown-asciidoc/converter.rb

@@ -1,50 +1,8 @@
 # encoding: UTF-8
 module Kramdown; module AsciiDoc
-  using CoreExt
-
-  DEFAULT_PARSER_OPTS = {
-    auto_ids: false,
-    hard_wrap: false,
-    html_to_native: true,
-    input: 'GFM',
-  }
-
-  TocDirectiveTip = '<!-- TOC '
-  TocDirectiveRx = /^<!-- TOC .*<!-- \/TOC -->/m
-
-  # TODO return original source if YAML can't be parsed
-  def self.extract_front_matter source, attributes
-    if (line_i = (lines = source.each_line).first) && line_i.chomp == '---'
-      lines = lines.drop 1
-      front_matter = []
-      while (line = lines.shift) && line.chomp != '---'
-        front_matter << line
-      end
-      return source unless line && line.chomp == '---' && !(front_matter.include? ?\n)
-      lines.shift while (line = lines[0]) && line == ?\n
-      (::YAML.load front_matter.join).each do |key, val|
-        if key == 'layout'
-          attributes['page-layout'] = val unless val == 'default'
-        else
-          attributes[key] = val.to_s
-        end
-      end unless front_matter.empty?
-      lines.join
-    else
-      source
-    end
-  end
-
-  def self.replace_toc source, attributes
-    if source.include? TocDirectiveTip
-      attributes['toc'] = 'macro'
-      source.gsub TocDirectiveRx, 'toc::[]'
-    else
-      source
-    end
-  end
-
   class Converter < ::Kramdown::Converter::Base
+    using CoreExt
+
     RESOLVE_ENTITY_TABLE = { 38 => '&', 60 => '<', 62 => '>', 124 => '|' }
     ADMON_LABELS = %w(Note Tip Caution Warning Important Attention Hint).map {|l| [l, l] }.to_h
     ADMON_MARKERS = ADMON_LABELS.map {|l, _| %(#{l}: ) }
@@ -54,7 +12,7 @@ module Kramdown; module AsciiDoc
     BLOCK_TYPES = [:p, :blockquote, :codeblock, :table]
     DLIST_MARKERS = %w(:: ;; ::: ::::)
     NON_DEFAULT_TABLE_ALIGNMENTS = [:center, :right]
-    PUNCTUATION = %w(. ? !)
+    STOP_PUNCTUATION = %w(. ? ! ;)
     # FIXME here we reverse the smart quotes; add option to allow them (needs to be handled carefully)
     SMART_QUOTE_ENTITY_TO_MARKUP = { ldquo: ?", rdquo: ?", lsquo: ?', rsquo: ?' }
     TYPOGRAPHIC_SYMBOL_TO_MARKUP = {
@@ -83,13 +41,13 @@ module Kramdown; module AsciiDoc
 
     CommentPrefixRx = /^ *! ?/m
     CssPropDelimRx = /\s*;\s*/
-    FullStopRx = /(?<=\S\.|.\?|.!)\p{Blank}+/
     InadvertentReplacementsRx = /[-=]>|<[-=]|\.\.\.|\{\p{Word}[\p{Word}-]*\}/
     InvalidIdCharsRx = /&(?:[a-z][a-z]+\d{0,2}|#\d\d\d{0,4}|#x[\da-f][\da-f][\da-f]{0,3});|[^ \p{Word}\-.]+?/
     ListMarkerRx = /^[ \t]*(?:(?:-|\*\*{0,4}|\.\.{0,4}|\d+\.|[a-zA-Z]\.|[IVXivx]+\))[ \t]|.*?(?::::{0,2}|;;)(?:$|[ \t]))/
     MenuRefRx = /^([\p{Word}&].*?)\s>\s([\p{Word}&].*(?:\s>\s|$))+/
     ReplaceableTextRx = /[-=]>|<[-=]| -- |\p{Word}--\p{Word}|\*\*|\.\.\.|&\S+;|\{\p{Word}[\p{Word}-]*\}|(?:https?|ftp):\/\/\p{Word}|\((?:C|R|TM)\)/
     SmartApostropheRx = /\b’\b/
+    StopPunctRx = /(?<=\S[.;]|.\?|.!)\p{Blank}+/
     TrailingSpaceRx = / +$/
     TypographicSymbolRx = /[“”‘’—–…]/
     UriSchemeRx = /(?:https?|ftp):\/\/\p{Word}/
@@ -617,8 +575,13 @@ module Kramdown; module AsciiDoc
 
     def convert_xml_comment el, opts
       writer = opts[:writer]
-      XmlCommentRx =~ el.value
-      lines = (($1.include? ' !') ? ($1.gsub CommentPrefixRx, '').strip : $1.strip).split LF
+      if (val = (XmlCommentRx.match el.value)[1]).include? ' !'
+        lines = (val.gsub CommentPrefixRx, '').strip.split LF
+      elsif (val = val.strip).empty? && !writer.follows_list?
+        return
+      else
+        lines = val.split LF
+      end
       #siblings = (parent = opts[:parent]) ? parent.children : []
       if (el.options[:category] == :block)# || (!opts[:result][-1] && siblings[-1] == el)
         writer.start_block
@@ -730,7 +693,7 @@ module Kramdown; module AsciiDoc
       end
       if ventilate
         result.map {|line|
-          (line.start_with? '//') || !(PUNCTUATION.any? {|punc| line.include? punc }) ? line : (line.gsub FullStopRx, LF)
+          (line.start_with? '//') || !(STOP_PUNCTUATION.any? {|punc| line.include? punc }) ? line : (line.gsub StopPunctRx, LF)
         }.join LF
       else
         result.join LF
@@ -779,5 +742,3 @@ module Kramdown; module AsciiDoc
     end
   end
 end; end
-
-Kramdown::Converter::Asciidoc = Kramdown::AsciiDoc::Converter

data/lib/kramdown-asciidoc/kramdown_ext/parser/base.rb

@@ -1,5 +1,12 @@
 class Kramdown::Parser::Base
-  # Overload parse to force value of :auto_ids option to false; handled by converter instead
+  # Overload the parse method to force value of the :auto_ids option to false.
+  #
+  # The :auto_ids logic is handled instead by the Kramdown::AsciiDoc::Converter class
+  #
+  # @param source [String] the Markdown source string to parse.
+  # @param options [Hash] additional options to configure parsing.
+  #
+  # @return [Array<Kramdown::Element, Array>] a tuple of the document root element and a list of warning objects.
   def self.parse source, options
     (parser = new source, (options.merge auto_ids: false, auto_id_stripping: false)).parse
     [parser.root, parser.warnings]

data/lib/kramdown-asciidoc/kramdown_ext/parser/html.rb

@@ -1,5 +1,9 @@
 class Kramdown::Parser::Html::ElementConverter
-  # Overload convert_br to add the :html_tag option to indicate this br element originates from an HTML tag
+  # Overload the convert_br method to add the :html_tag option to indicate this element originates from an HTML tag.
+  #
+  # @param el [Kramdown::Element] The element that represents an HTML br tag.
+  #
+  # @return [void]
   def convert_br el
     el.options.replace location: el.options[:location], html_tag: true
     el.type = el.value.to_sym