Define the public API using YARD/semver

.yardopts

@@ -3,7 +3,6 @@
 -M kramdown
 -o yardoc
 -r ./README.md
---private
 --protected
 --asset ./doc/css/common.css:css/common.css
 --verbose

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

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;
 

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;

lib/oga/lru.rb

@@ -21,6 +21,8 @@ module Oga
   #
   #     cache.keys # => [:b, :c, :d]
   #
+  # @api private
+  #
   class LRU
     ##
     # @param [Fixnum] maximum

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

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 = '*'

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;
 

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;