From df96b3d3bb1c4631d69fb298b39009c3e238bfa9 Mon Sep 17 00:00:00 2001
From: Yorick Peterse <yorickpeterse@gmail.com>
Date: Mon, 11 May 2015 21:34:34 +0200
Subject: [PATCH] Define the public API using YARD/semver

---
 .yardopts                  | 1 -
 README.md                  | 5 +++++
 lib/oga/css/lexer.rl       | 2 ++
 lib/oga/css/parser.rll     | 2 ++
 lib/oga/lru.rb             | 2 ++
 lib/oga/node_name_set.rb   | 2 ++
 lib/oga/xpath/evaluator.rb | 2 ++
 lib/oga/xpath/lexer.rl     | 2 ++
 lib/oga/xpath/parser.rll   | 2 ++
 9 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/.yardopts b/.yardopts
index e74ab64..4f840dc 100644
--- a/.yardopts
+++ b/.yardopts
@@ -3,7 +3,6 @@
 -M kramdown
 -o yardoc
 -r ./README.md
---private
 --protected
 --asset ./doc/css/common.css:css/common.css
 --verbose
diff --git a/README.md b/README.md
index cd786ee..a77bf5f 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,10 @@ From [Wikipedia][oga-wikipedia]:
 > power saws. One person stood on a raised platform, with the board below him,
 > and the other person stood underneath them.
 
+Oga uses [Semantic Versioning 2.0][semver] as its versioning scheme. All
+classes, modules and methods are part of the public API _unless_ they are
+declared as private using Ruby's `private` keyword or YARD's `@api private` tag.
+
 ## Examples
 
 Parsing a simple string of XML:
@@ -303,3 +307,4 @@ in the root directory of this repository.
 [oga-wikipedia]: https://en.wikipedia.org/wiki/Japanese_saw#Other_Japanese_saws
 [ox]: https://github.com/ohler55/ox
 [doc-website]: http://code.yorickpeterse.com/oga/latest/
+[semver]: http://semver.org/spec/v2.0.0.html
diff --git a/lib/oga/css/lexer.rl b/lib/oga/css/lexer.rl
index 0ae936c..4a9bd5c 100644
--- a/lib/oga/css/lexer.rl
+++ b/lib/oga/css/lexer.rl
@@ -16,6 +16,8 @@ module Oga
     # multiple threads. However, no global state is used so you can use separate
     # instances in threads just fine.
     #
+    # @api private
+    #
     class Lexer
       %% write data;
 
diff --git a/lib/oga/css/parser.rll b/lib/oga/css/parser.rll
index 83d9651..a52f752 100644
--- a/lib/oga/css/parser.rll
+++ b/lib/oga/css/parser.rll
@@ -10,6 +10,8 @@
 # Similar to {Oga::XPath::Parser} this parser only takes String instances as
 # input.
 #
+# @api private
+#
 }
 
 %name Oga::CSS::Parser;
diff --git a/lib/oga/lru.rb b/lib/oga/lru.rb
index 1fe98b5..50b85ac 100644
--- a/lib/oga/lru.rb
+++ b/lib/oga/lru.rb
@@ -21,6 +21,8 @@ module Oga
   #
   #     cache.keys # => [:b, :c, :d]
   #
+  # @api private
+  #
   class LRU
     ##
     # @param [Fixnum] maximum
diff --git a/lib/oga/node_name_set.rb b/lib/oga/node_name_set.rb
index 3d0c57d..75c794c 100644
--- a/lib/oga/node_name_set.rb
+++ b/lib/oga/node_name_set.rb
@@ -3,6 +3,8 @@ module Oga
   # Class for storing (HTML) element names in a set and automatically adding
   # their uppercase equivalents.
   #
+  # @api private
+  #
   class NodeNameSet < Set
     ##
     # @param [Array] values
diff --git a/lib/oga/xpath/evaluator.rb b/lib/oga/xpath/evaluator.rb
index 0e9a40c..f6dd359 100644
--- a/lib/oga/xpath/evaluator.rb
+++ b/lib/oga/xpath/evaluator.rb
@@ -58,6 +58,8 @@ module Oga
     #
     #     evaluator.evaluate('$number') # => 10
     #
+    # @api private
+    #
     class Evaluator
       # Wildcard for node names/namespace prefixes.
       STAR = '*'
diff --git a/lib/oga/xpath/lexer.rl b/lib/oga/xpath/lexer.rl
index dd46588..898ca34 100644
--- a/lib/oga/xpath/lexer.rl
+++ b/lib/oga/xpath/lexer.rl
@@ -32,6 +32,8 @@ module Oga
     # use separate instances per thread as there is no global (= class level)
     # shared state.
     #
+    # @api private
+    #
     class Lexer
       %% write data;
 
diff --git a/lib/oga/xpath/parser.rll b/lib/oga/xpath/parser.rll
index 4b97f3e..d848dfc 100644
--- a/lib/oga/xpath/parser.rll
+++ b/lib/oga/xpath/parser.rll
@@ -6,6 +6,8 @@
 #
 # Unlike {Oga::XML::Parser} this parser only takes String instances as input.
 #
+# @api private
+#
 }
 
 %name Oga::XPath::Parser;