Merge pull request #1484 from manicmaniac/fix-yard-doc

Fix broken YARD documents

.yardopts

@@ -0,0 +1,4 @@
+--markup=markdown
+--load docs/yard_support.rb
+--tag tags:tags
+--tag availability:availability

CHANGELOG.md

@@ -14,6 +14,7 @@
 * Always use `LocalOnlyGitRepo` source with `dry_run` command - [@imaginaris](https://github.com/imaginaris) [#1452](https://github.com/danger/danger/pull/1452)
 * Support repository access token on Bitbucket Cloud - [@manicmaniac](https://github.com/manicmaniac) [#1481](https://github.com/danger/danger/pull/1481)
 * Update "What is Danger?" in README - [@manicmaniac](https://github.com/manicmaniac) [#1482](https://github.com/danger/danger/pull/1482)
+* Fix broken YARD documents - [@manicmaniac](https://github.com/manicmaniac) [#1484](https://github.com/danger/danger/pull/1484)
 <!-- Your comment above here -->
 
 ## 9.4.3

docs/yard_support.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+
+# Custom markup provider class that always renders Kramdown using GFM (Github Flavored Markdown).
+# @see https://stackoverflow.com/a/63683511/6918498
+class KramdownGfmDocument < Kramdown::Document
+ def initialize(source, options = {})
+ options[:input] = "GFM" unless options.key?(:input)
+ super(source, options)
+ end
+end
+
+# Register the new provider as the highest priority option for Markdown.
+YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown].insert(0, { const: KramdownGfmDocument.name })

lib/danger/ci_source/azure_pipelines.rb

@@ -19,7 +19,7 @@ module Danger
  # #### GitHub
  #
  # You need to add the `DANGER_GITHUB_API_TOKEN` environment variable, to do this, go to your build definition's variables tab.
- # #
+ #
  # #### Azure Git
  #
  # You need to add the `DANGER_VSTS_API_TOKEN` and `DANGER_VSTS_HOST` environment variable, to do this,

lib/danger/ci_source/bitrise.rb

@@ -19,13 +19,13 @@ module Danger
  #
  # Add the `DANGER_GITHUB_API_TOKEN` to your workflow's [Secret App Env Vars](https://blog.bitrise.io/anyone-even-prs-can-have-secrets).
  #
- # ### bitbucket server and bitrise
+ # ### Bitbucket Server and Bitrise
  #
- # Danger will read the environment variable GIT_REPOSITORY_URL to construct the Bitbucket Server API URL
- # finding the project and repo slug in the GIT_REPOSITORY_URL variable. This GIT_REPOSITORY_URL variable
+ # Danger will read the environment variable `GIT_REPOSITORY_URL` to construct the Bitbucket Server API URL
+ # finding the project and repo slug in the `GIT_REPOSITORY_URL` variable. This `GIT_REPOSITORY_URL` variable
  # comes from the App Settings tab for your Bitrise App. If you are manually setting a repo URL in the
  # Git Clone Repo step, you may need to set adjust this property in the settings tab, maybe even fake it.
- # The patterns used are `(%r{\.com/(.*)})` and `(%r{\.com:(.*)})` and .split(/\.git$|$/) to remove ".git" if the URL contains it.
+ # The patterns used are `(%r{\.com/(.*)})` and `(%r{\.com:(.*)})` and `.split(/\.git$|$/)` to remove ".git" if the URL contains it.
  #
  class Bitrise < CI
  def self.validates_as_ci?(env)

lib/danger/ci_source/code_build.rb

@@ -4,8 +4,8 @@
 module Danger
  # ### CI Setup
  #
- # In CodeBuild, make sure to correctly forward CODEBUILD_BUILD_ID, CODEBUILD_SOURCE_VERSION, CODEBUILD_SOURCE_REPO_URL and DANGER_GITHUB_API_TOKEN.
- # In CodeBuild with batch builds, make sure to correctly forward CODEBUILD_BUILD_ID, CODEBUILD_WEBHOOK_TRIGGER, CODEBUILD_SOURCE_REPO_URL, CODEBUILD_BATCH_BUILD_IDENTIFIER and DANGER_GITHUB_API_TOKEN.
+ # In CodeBuild, make sure to correctly forward `CODEBUILD_BUILD_ID`, `CODEBUILD_SOURCE_VERSION`, `CODEBUILD_SOURCE_REPO_URL` and `DANGER_GITHUB_API_TOKEN`.
+ # In CodeBuild with batch builds, make sure to correctly forward `CODEBUILD_BUILD_ID`, `CODEBUILD_WEBHOOK_TRIGGER`, `CODEBUILD_SOURCE_REPO_URL`, `CODEBUILD_BATCH_BUILD_IDENTIFIER` and `DANGER_GITHUB_API_TOKEN`.
  #
  # ### Token Setup
  #

lib/danger/ci_source/local_git_repo.rb

@@ -14,7 +14,6 @@
 require "danger/ci_source/support/commits"
 
 module Danger
- # ignore
  class LocalGitRepo < CI
  attr_accessor :base_commit, :head_commit
 

lib/danger/danger_core/plugins/dangerfile_github_plugin.rb

@@ -237,7 +237,7 @@ def html_link(paths, full_path: true)
  # @!group GitHub Misc
  # Use to ignore inline messages which lay outside a diff's range, thereby not posting them in the main comment.
  # You can set hash to change behavior per each kinds. (ex. `{warning: true, error: false}`)
- # @param [Bool] or [Hash<Symbol, Bool>] dismiss
+ # @param [Bool or Hash<Symbol, Bool>] dismiss
  # Ignore out of range inline messages, defaults to `true`
  #
  # @return [void]

lib/danger/danger_core/plugins/dangerfile_gitlab_plugin.rb

@@ -248,7 +248,7 @@ def html_link(paths, full_path: true)
  # @!group Gitlab Misc
  # Use to ignore inline messages which lay outside a diff's range, thereby not posting the comment.
  # You can set hash to change behavior per each kinds. (ex. `{warning: true, error: false}`)
- # @param [Bool] or [Hash<Symbol, Bool>] dismiss
+ # @param [Bool or Hash<Symbol, Bool>] dismiss
  # Ignore out of range inline messages, defaults to `true`
  #
  # @return [void]

lib/danger/danger_core/plugins/dangerfile_messaging_plugin.rb

@@ -13,12 +13,13 @@ module Danger
  # If it's not called again on subsequent runs.
  #
  # Each of `message`, `warn`, `fail` and `markdown` support multiple passed arguments
- # @example
  #
- # message 'Hello', 'World', file: "Dangerfile", line: 1
- # warn ['This', 'is', 'warning'], file: "Dangerfile", line: 1
- # failure 'Ooops', 'bad bad error', sticky: false
- # markdown '# And', '# Even', '# Markdown', file: "Dangerfile", line: 1
+ # @example Multiple passed arguments
+ #
+ # message 'Hello', 'World', file: "Dangerfile", line: 1
+ # warn ['This', 'is', 'warning'], file: "Dangerfile", line: 1
+ # failure 'Ooops', 'bad bad error', sticky: false
+ # markdown '# And', '# Even', '# Markdown', file: "Dangerfile", line: 1
  #
  # By default, using `failure` would fail the corresponding build. Either via an API call, or
  # via the return value for the danger command. Older code examples use `fail` which is an alias
@@ -87,11 +88,12 @@ def self.instance_name
  # @!group Core
  # Print markdown to below the table
  #
- # @param [String, Array<String>] message
+ # @param [Hash] options
+ # @option [String, Array<String>] markdowns
  # The markdown based message to be printed below the table
- # @param  [String] file
+ # @option [String] file
  # Optional. Path to the file that the message is for.
- # @param  [String] line
+ # @option [String] line
  # Optional. The line in the file to present the message in.
  # @return [void]
  #
@@ -107,14 +109,15 @@ def markdown(*markdowns, **options)
  # @!group Core
  # Print out a generate message on the PR
  #
- # @param [String, Array<String>] message
+ # @param [String, Array<String>] messages
  # The message to present to the user
- # @param [Boolean] sticky
+ # @param [Hash] options
+ # @option [Boolean] sticky
  # Whether the message should be kept after it was fixed,
  # defaults to `false`.
- # @param  [String] file
+ # @option [String] file
  # Optional. Path to the file that the message is for.
- # @param  [String] line
+ # @option [String] line
  # Optional. The line in the file to present the message in.
  # @return [void]
  #
@@ -131,14 +134,15 @@ def message(*messages, **options)
  # @!group Core
  # Specifies a problem, but not critical
  #
- # @param [String, Array<String>] message
+ # @param [String, Array<String>] warnings
  # The message to present to the user
- # @param [Boolean] sticky
+ # @param options
+ # @option [Boolean] sticky
  # Whether the message should be kept after it was fixed,
  # defaults to `false`.
- # @param  [String] file
+ # @option [String] file
  # Optional. Path to the file that the message is for.
- # @param  [String] line
+ # @option [String] line
  # Optional. The line in the file to present the message in.
  # @return [void]
  #
@@ -157,14 +161,15 @@ def warn(*warnings, **options)
  # @!group Core
  # Declares a CI blocking error
  #
- # @param [String, Array<String>] message
+ # @param [String, Array<String>] failures
  # The message to present to the user
- # @param [Boolean] sticky
+ # @param options
+ # @option [Boolean] sticky
  # Whether the message should be kept after it was fixed,
  # defaults to `false`.
- # @param  [String] file
+ # @option [String] file
  # Optional. Path to the file that the message is for.
- # @param  [String] line
+ # @option [String] line
  # Optional. The line in the file to present the message in.
  # @return [void]
  #

lib/danger/helpers/comments_helper.rb

@@ -14,14 +14,14 @@ def markdown_parser(text)
  Kramdown::Document.new(text, input: "GFM", smart_quotes: %w(apos apos quot quot))
  end
 
- # !@group Extension points
+ # @!group Extension points
  # Produces a markdown link to the file the message points to
  #
  # request_source implementations are invited to override this method with their
  # vendor specific link.
  #
  # @param [Violation or Markdown] message
- # @param [Bool] Should hide any generated link created
+ # @param [Bool] hide_link Should hide any generated link created
  #
  # @return [String] The Markdown compatible link
  def markdown_link_to_message(message, hide_link)
@@ -30,7 +30,7 @@ def markdown_link_to_message(message, hide_link)
  "#{message.file}#L#{message.line}"
  end
 
- # !@group Extension points
+ # @!group Extension points
  # Determine whether two messages are equivalent
  #
  # request_source implementations are invited to override this method.
@@ -46,6 +46,8 @@ def messages_are_equivalent(m1, m2)
  m1 == m2
  end
 
+ # @endgroup
+
  def process_markdown(violation, hide_link = false)
  message = violation.message
  message = "#{markdown_link_to_message(violation, hide_link)}#{message}" if violation.file && violation.line

lib/danger/helpers/comments_parsing_helper.rb

@@ -1,7 +1,7 @@
 module Danger
  module Helpers
  module CommentsParsingHelper
- # !@group Extension points
+ # @!group Extension points
  # Produces a message-like from a row in a comment table
  #
  # @param [String] row
@@ -12,6 +12,8 @@ def parse_message_from_row(row)
  Violation.new(row, true)
  end
 
+ # @endgroup
+
  def parse_tables_from_comment(comment)
  comment.split("</table>")
  end