Merge pull request Homebrew#10969 from reitermarkus/yard

Move YARD config into `Library/Homebrew`.

.gitignore

@@ -32,6 +32,9 @@
 **/vendor/bundle/ruby/*/gems/*/*
 **/vendor/bundle/ruby/*/specifications
 
+# Ignore YARD files
+**/.yardoc
+
 # Unignore vendored gems
 !**/vendor/bundle/ruby/*/gems/*/lib
 !**/vendor/bundle/ruby/*/gems/rubocop-performance-*/config

Library/Homebrew/.yardopts

@@ -0,0 +1,12 @@
+--title "Homebrew Ruby API"
+--main README.md
+--markup markdown
+--no-private
+--load yard/ignore_directives.rb
+--template-path yard/templates
+--exclude test/
+--exclude vendor/
+--exclude compat/
+**/*.rb
+-
+*.md

Library/Homebrew/README.md

@@ -1,6 +1,6 @@
-# Homebrew's Formula API
+# Homebrew Ruby API
 
-This is the public API for Homebrew.
+This is the public API for [Homebrew](https://github.com/Homebrew).
 
 The main class you should look at is the {Formula} class (and classes linked from there). That's the class that's used to create Homebrew formulae (i.e. package descriptions). Assume anything else you stumble upon is private.
 

Library/Homebrew/sorbet/rbi/todo.rbi

@@ -3,6 +3,8 @@
 
 # typed: strong
 module ::StackProf; end
+module ::YARD::Docstring; end
+module ::YARD::DocstringParser; end
 module DependencyCollector::Compat; end
 module GitHubPackages::JSONSchemer; end
 module OS::Mac::Version::NULL; end

Library/Homebrew/yard/ignore_directives.rb

@@ -0,0 +1,11 @@
+# typed: false
+# frozen_string_literal: true
+
+# from https://github.com/lsegal/yard/issues/484#issuecomment-442586899
+class IgnoreDirectiveDocstringParser < YARD::DocstringParser
+  def parse_content(content)
+    super(content&.sub(/(\A(typed|.*rubocop)|TODO):.*/m, ""))
+  end
+end
+
+YARD::Docstring.default_parser = IgnoreDirectiveDocstringParser

Library/Homebrew/yard/templates/default/docstring/html/internal.erb

@@ -0,0 +1,5 @@
+<p class="note private">
+  <strong>This <%= object.type %> is part of an internal API.</strong>
+  This <%= object.type %> may only be used internally in repositories owned by <a href="https://github.com/Homebrew">Homebrew</a>, except in casks or formulae.
+  Third parties should avoid using this <%= object.type %> if possible, as it may be removed or be changed without warning.
+</p>

Library/Homebrew/yard/templates/default/docstring/html/private.erb

@@ -0,0 +1,5 @@
+<p class="note private">
+  <strong>This <%= object.type %> is part of a private API.</strong>
+  This <%= object.type %> may only be used in the <a href="https://github.com/Homebrew/brew">Homebrew/brew</a> repository.
+  Third parties should avoid using this <%= object.type %> if possible, as it may be removed or be changed without warning.
+</p>

Library/Homebrew/yard/templates/default/docstring/html/setup.rb

@@ -0,0 +1,14 @@
+# typed: false
+# frozen_string_literal: true
+
+def init
+  super
+
+  return if sections.empty?
+
+  sections[:index].place(:internal).before(:private)
+end
+
+def internal
+  erb(:internal) if object.has_tag?(:api) && object.tag(:api).text == "internal"
+end

Library/Homebrew/yard/templates/default/module/html/item_summary.erb

@@ -0,0 +1,39 @@
+
+<li class="<%= @item.visibility %> <%= @item.has_tag?(:deprecated) ? 'deprecated' : '' %>">
+  <span class="summary_signature">
+    <% if @item.tags(:overload).size == 1 %>
+      <%= signature(@item.tag(:overload), true, false, !@item.attr_info) %>
+    <% else %>
+      <%= signature(@item, true, false, !@item.attr_info) %>
+    <% end %>
+    <% if @item.aliases.size > 0 %>
+      (also: <%= @item.aliases.map {|o| h(o.name(true)) }.join(", ") %>)
+    <% end %>
+  </span>
+  <% if object != @item.namespace %>
+    <span class="note title not_defined_here">
+      <%= @item.namespace.type == :class ? 'inherited' : (@item.scope == :class ? 'extended' : 'included') %>
+      from <%= linkify @item, object.relative_path(@item.namespace) %>
+    </span>
+  <% end %>
+  <% if @item.constructor? %>
+    <span class="note title constructor">constructor</span>
+  <% end %>
+  <% if rw = @item.attr_info %>
+    <% if !run_verifier([rw[:read]].compact).empty? && run_verifier([rw[:write]].compact).empty? %>
+      <span class="note title readonly">readonly</span>
+    <% end %>
+    <% if !run_verifier([rw[:write]].compact).empty? && run_verifier([rw[:read]].compact).empty? %>
+      <span class="note title writeonly">writeonly</span>
+    <% end %>
+  <% end %>
+  <% if @item.visibility != :public %><span class="note title <%= @item.visibility %>"><%= @item.visibility %></span><% end %>
+  <% if @item.has_tag?(:abstract) %><span class="abstract note title">abstract</span><% end %>
+  <% if @item.has_tag?(:deprecated) %><span class="deprecated note title">deprecated</span><% end %>
+  <% if @item.has_tag?(:api) && @item.tag(:api).text != 'public' %><span class="private note title"><%= @item.tag(:api).text %></span><% end %>
+  <% if @item.has_tag?(:deprecated) %>
+    <span class="summary_desc"><strong>Deprecated.</strong> <%= htmlify_line @item.tag(:deprecated).text %></span>
+  <% else %>
+    <span class="summary_desc"><%= htmlify_line docstring_summary(@item) %></span>
+  <% end %>
+</li>