Add public API markers to targets and base tasks used by plugins.

Foursquare has plugins that use these internally and they appear
to be things that would be of use to task or plugin developers.

The targets are self explanatory - we consume products of these
targets in plugin tasks. The fingerprint strategy is a core tool
in a task developer's toolbox.

If the task involves jvm code, then it may need do jar operations,
this exposes as public some of those tasks.

Ivy is marked public because it provides a custom exception that
doesn't inherit from anything descriptive - Ivy.Error is just an
Exception. We publish jars with a custom pom-publish task - where
every jar has a common version. Catching Ivy failures required
catching Ivy.Error.

Testing Done:
I ran the unit tests locally to catch style or syntax errors.
Running the CI to be sure since we are getting so close to release.

https://travis-ci.org/pantsbuild/pants/builds/125091874

Bugs closed: 3253

Reviewed at https://rbcommons.com/s/twitter/r/3746/

src/python/pants/backend/codegen/targets/python_thrift_library.py

@@ -9,7 +9,10 @@
 
 
 class PythonThriftLibrary(PythonTarget):
-  """A Python library generated from Thrift IDL files."""
+  """A Python library generated from Thrift IDL files.
+
+  :API: public
+  """
 
   def __init__(self, **kwargs):
     """

src/python/pants/backend/jvm/targets/jarable.py

@@ -12,7 +12,10 @@
 
 
 class Jarable(AbstractClass):
-  """A mixin that identifies a target as one that can provide a jar."""
+  """A mixin that identifies a target as one that can provide a jar.
+
+  :API: public
+  """
 
   @abstractproperty
   def identifier(self):

src/python/pants/backend/jvm/targets/jvm_app.py

@@ -185,6 +185,8 @@ class JvmApp(Target):
   self-contained artifact suitable for deployment on some other machine.
   The artifact contains the executable jar, its dependencies, and
   extra files like config files, startup scripts, etc.
+
+  :API: public
   """
 
   def __init__(self, name=None, payload=None, binary=None, bundles=None, basename=None, **kwargs):

src/python/pants/backend/jvm/tasks/jar_task.py

@@ -33,6 +33,8 @@ class Jar(object):
   Upon construction the jar is conceptually opened for writes.  The write methods are called to
   add to the jar's contents and then changes are finalized with a call to close.  If close is not
   called the staged changes will be lost.
+
+  :API: public
   """
 
   class Error(Exception):
@@ -326,7 +328,10 @@ def open_jar(self, path, overwrite=False, compressed=True, jar_rules=None):
 class JarBuilderTask(JarTask):
 
   class JarBuilder(AbstractClass):
-    """A utility to aid in adding the classes and resources associated with targets to a jar."""
+    """A utility to aid in adding the classes and resources associated with targets to a jar.
+
+    :API: public
+    """
 
     @staticmethod
     def _add_agent_manifest(agent, manifest):

src/python/pants/backend/jvm/tasks/jvm_binary_task.py

@@ -22,6 +22,10 @@
 
 
 class JvmBinaryTask(JarBuilderTask):
+  """Encapsulates operations to build or update JvmBinary jars.
+
+  :API: public
+  """
 
   @staticmethod
   def is_binary(target):

src/python/pants/backend/jvm/tasks/scala_repl.py

@@ -16,6 +16,11 @@
 
 
 class ScalaRepl(JvmToolTaskMixin, ReplTaskMixin, JvmTask):
+  """Operations to create or launch Scala repls.
+
+  :API: public
+  """
+
   _RUNNER_MAIN = 'org.pantsbuild.tools.runner.PantsRunner'
 
   @classmethod

src/python/pants/backend/python/targets/python_binary.py

@@ -22,6 +22,8 @@ class PythonBinary(PythonTarget):
   scripts that contain a complete Python environment capable of
   running the target. For more information about pex files see
   http://pantsbuild.github.io/python-readme.html#how-pex-files-work.
+
+  :API: public
   """
 
   # TODO(wickman) Consider splitting pex options out into a separate PexInfo builder that can be

src/python/pants/backend/python/targets/python_requirement_library.py

@@ -13,7 +13,10 @@
 
 
 class PythonRequirementLibrary(Target):
-  """A set of pip requirements."""
+  """A set of pip requirements.
+
+  :API: public
+  """
 
   def __init__(self, payload=None, requirements=None, **kwargs):
     """

src/python/pants/backend/python/targets/python_target.py

@@ -19,7 +19,10 @@
 
 
 class PythonTarget(Target):
-  """Base class for all Python targets."""
+  """Base class for all Python targets.
+
+  :API: public
+  """
 
   def __init__(self,
                address=None,

src/python/pants/ivy/ivy.py

@@ -21,6 +21,8 @@
 class Ivy(object):
   """Encapsulates the ivy cli taking care of the basic invocation letting you just worry about the
   args to pass to the cli itself.
+
+  :API: public
   """
 
   class Error(Exception):