Generate RDoc documentation.

This is currently still very messy and we probably want to work out the
best way to declare what parts of our DSL/what files are "public".

Still, even if this is a WIP I'd rather get something committed sooner
rather than later and start iterating on this as a replacement for
`example_formula.rb` and the formula cookbook.

To test:
```bash
cd $(brew --prefix)/Library/Homebrew && \
  rdoc formula.rb requirement.rb utils.rb &&\
  open doc/index.html
```

Closes Homebrew/homebrew#32470.

.gitignore

@@ -11,6 +11,7 @@
 !/bin/brew
 !/share/man/man1/brew.1
 .DS_Store
+/Library/Homebrew/doc
 /Library/LinkedKegs
 /Library/PinnedKegs
 /Library/Taps

Library/Homebrew/.rdoc_options

@@ -0,0 +1,17 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+- .
+charset: UTF-8
+exclude:
+hyperlink_all: false
+line_numbers: true
+main_page:
+markup: rdoc
+page_dir:
+show_hash: false
+tab_width: 2
+title: Homebrew
+visibility: :protected
+webcvs:

Library/Homebrew/formula.rb

@@ -11,9 +11,11 @@ require 'install_renamed'
 require 'pkg_version'
 
 class Formula
+  # :startdoc:
   include FileUtils
   include Utils::Inreplace
   extend Enumerable
+  # :stopdoc:
 
   attr_reader :name, :path
   attr_reader :stable, :devel, :head, :active_spec
@@ -138,6 +140,8 @@ class Formula
     Keg.new(installed_prefix).version
   end
 
+  # :startdoc:
+
   # The directory in the cellar that the formula is installed to.
   # This directory contains the formula's name and version.
   def prefix(v=pkg_version)
@@ -250,6 +254,8 @@ class Formula
     false
   end
 
+  # :stopdoc:
+
   # yields self with current working directory set to the uncompressed tarball
   def brew
     validate_attributes :name, :version
@@ -315,6 +321,8 @@ class Formula
     "#<#{self.class.name}: #{path}>"
   end
 
+  # :startdoc:
+
   # Standard parameters for CMake builds.
   # Using Build Type "None" tells cmake to use our CFLAGS,etc. settings.
   # Setting it to Release would ignore our flags.
@@ -333,6 +341,8 @@ class Formula
     ]
   end
 
+  # :stopdoc:
+
   # Deprecated
   def python(options={}, &block)
     opoo 'Formula#python is deprecated and will go away shortly.'
@@ -492,6 +502,8 @@ class Formula
 
   protected
 
+  # :startdoc:
+
   # Pretty titles the command and buffers stdout/stderr
   # Throws if there's an error
   def system cmd, *args
@@ -554,6 +566,8 @@ class Formula
     end
   end
 
+  # :stopdoc:
+
   private
 
   def exec_cmd(cmd, args, out, logfn)

Library/Homebrew/requirement.rb

@@ -3,6 +3,8 @@ require 'dependency'
 require 'dependencies'
 require 'build_environment'
 
+# :startdoc:
+
 # A base class for non-formula requirements needed by formulae.
 # A "fatal" requirement is one that will fail the build if it is not present.
 # By default, Requirements are non-fatal.
@@ -104,6 +106,8 @@ class Requirement
     super(cmd, ORIGINAL_PATHS.join(File::PATH_SEPARATOR))
   end
 
+  # :stopdoc:
+
   class << self
     include BuildEnvironmentDSL
 

Library/Homebrew/utils.rb

@@ -42,6 +42,8 @@ class Tty
   end
 end
 
+# :startdoc:
+
 def ohai title, *sput
   title = Tty.truncate(title) if $stdout.tty? && !ARGV.verbose?
   puts "#{Tty.blue}==>#{Tty.white} #{title}#{Tty.reset}"
@@ -71,6 +73,8 @@ def odie error
   exit 1
 end
 
+# :stopdoc:
+
 def pretty_duration s
   return "2 seconds" if s < 3 # avoids the plural problem ;)
   return "#{s.to_i} seconds" if s < 120