diff --git a/README.markdown b/README.markdown
index ee9d7621..93e6dd29 100644
--- a/README.markdown
+++ b/README.markdown
@@ -95,94 +95,7 @@ java::oracle { 'jdk8' :
 
 ## Reference
 
-### Classes
-
-#### Public classes
-
-* `java`: Installs and manages the Java package.
-
-#### Private classes
-
-* `java::config`: Configures the Java alternatives.
-
-* `java::params`: Builds a hash of jdk/jre packages for all compatible operating systems.
-
-
-#### Parameters
-
-The following parameters are available in `java`:
-
-##### `distribution`
-
-Specifies the Java distribution to install.
-Valid options:  'jdk', 'jre', or, where the platform supports alternative packages, 'sun-jdk', 'sun-jre', 'oracle-jdk', 'oracle-jre'. Default: 'jdk'.
-
-##### `java_alternative`
-
-Specifies the name of the Java alternative to use. If you set this parameter, *you must also set the `java_alternative_path`.*
-Valid options: Run command `update-java-alternatives -l` for a list of available choices. Default: OS and distribution dependent defaults on *deb systems, undef on others.
-
-##### `java_alternative_path`
-
-*Required when `java_alternative` is specified.* Defines the path to the `java` command.
-Valid option: String. Default: OS and distribution dependent defaults on *deb systems, undef on others.
-
-##### `package`
-
-Specifies the name of the Java package. This is configurable in case you want to install a non-standard Java package. If not set, the module installs the appropriate package for the `distribution` parameter and target platform. If you set `package`, the `distribution` parameter does nothing.
-Valid option: String. Default: undef.
-
-##### `version`
-
-Sets the version of Java to install, if you want to ensure a particular version.
-Valid options: 'present', 'installed', 'latest', or a string matching `/^[.+_0-9a-zA-Z:-]+$/`. Default: 'present'.
-
-#### Public defined types
-
-* `java::oracle`: Installs specified version of Oracle Java SE.  You may install multiple versions of Oracle Jave SE on the same node using this defined type.
-
-#### Parameters
-
-The following parameters are available in `java::oracle`:
-
-##### `version`
-Version of Java Standard Edition (SE) to install. 6, 7 or 8.
-
-##### `version_major`
-
-Major version of the Java Standard Edition (SE) to install. Must be used together with `version_minor`. For example, '8u101'.
-
-##### `version_minor`
-
-Minor version (or build version) of the Java Standard Edition (SE) to install. Must be used together with `version_major`. For example, 'b13'.
-
-##### `java_se`
-
-Type of Java SE to install, jdk or jre.
-
-##### `ensure`
-
-Install or remove the package.
-
-##### `oracle_url`
-
-Official Oracle URL to download the binaries from.
-
-##### `proxy_server`
-
-Specify a proxy server, with port number if needed. ie: https://example.com:8080. (passed to archive)
-
-##### `proxy_type`
-
-Proxy server type (none|http|https|ftp). (passed to archive)
-
-##### `url`
-
-Pass an entire URL to download the installer from rather than building the complete URL from other parameters. This will allow the module to be used even if the URLs are changed by Oracle. If this parameter is used, matching `version_major` and `version_minor` parameters must also be passed to the class.
-
-##### `url_hash`
-
-Directory hash used by the download.oracle.com site. This value is a 32 character string which is part of the file URL returned by the JDK download site.
+For information on the classes and types, see the [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-java/blob/master/REFERENCE.md). For information on the facts, see below.
 
 ### Facts
 
diff --git a/REFERENCE.md b/REFERENCE.md
new file mode 100644
index 00000000..6758ba5d
--- /dev/null
+++ b/REFERENCE.md
@@ -0,0 +1,257 @@
+# Reference
+<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
+
+## Table of Contents
+
+**Classes**
+
+_Public Classes_
+
+* [`java`](#java): This module manages the Java runtime package
+
+_Private Classes_
+
+* `java::config`: 
+* `java::params`: This class builds a hash of JDK/JRE packages and (for Debian)
+alternatives.  For wheezy/precise, we provide Oracle JDK/JRE
+options, even though those are not in the package repositories.
+
+**Defined types**
+
+* [`java::oracle`](#javaoracle): Installs Oracle Java. By using this module you agree to the Oracle licensing
+agreement.
+
+## Classes
+
+### java
+
+This module manages the Java runtime package
+
+#### Parameters
+
+The following parameters are available in the `java` class.
+
+##### `distribution`
+
+Data type: `String`
+
+The java distribution to install. Can be one of "jdk" or "jre",
+or other platform-specific options where there are multiple
+implementations available (eg: OpenJDK vs Oracle JDK).
+
+Default value: 'jdk'
+
+##### `version`
+
+Data type: `Pattern[/present|installed|latest|^[.+_0-9a-zA-Z:~-]+$/]`
+
+The version of java to install. By default, this module simply ensures
+that java is present, and does not require a specific version.
+
+Default value: 'present'
+
+##### `package`
+
+Data type: `Optional[String]`
+
+The name of the java package. This is configurable in case a non-standard
+java package is desired.
+
+Default value: `undef`
+
+##### `package_options`
+
+Data type: `Optional[Array]`
+
+Array of strings to pass installation options to the 'package' Puppet resource.
+Options available depend on the 'package' provider for the target OS.
+
+Default value: `undef`
+
+##### `java_alternative`
+
+Data type: `Optional[String]`
+
+The name of the java alternative to use on Debian systems.
+"update-java-alternatives -l" will show which choices are available.
+If you specify a particular package, you will almost always also
+want to specify which java_alternative to choose. If you set
+this, you also need to set the path below.
+
+Default value: `undef`
+
+##### `java_alternative_path`
+
+Data type: `Optional[String]`
+
+The path to the "java" command on Debian systems. Since the
+alternatives system makes it difficult to verify which
+alternative is actually enabled, this is required to ensure the
+correct JVM is enabled.
+
+Default value: `undef`
+
+##### `java_home`
+
+Data type: `Optional[String]`
+
+The path to where the JRE is installed. This will be set as an
+environment variable.
+
+Default value: `undef`
+
+## Defined types
+
+### java::oracle
+
+Defined Type java::oracle
+
+Install one or more versions of Oracle Java.
+
+Uses the following to download the package and automatically accept
+the licensing terms:
+```
+wget --no-cookies --no-check-certificate --header \
+"Cookie: gpw_e24=http%3A%2F%2Fwww.oracle.com%2F; oraclelicense=accept-securebackup-cookie" \
+"http://download.oracle.com/otn-pub/java/jdk/8u131-b11/d54c1d3a095b4ff2b6607d096fa80163/jdk-8u131-linux-x64.tar.gz"
+```
+
+#### Parameters
+
+The following parameters are available in the `java::oracle` defined type.
+
+##### `ensure`
+
+Data type: `Any`
+
+Install or remove the package.
+
+Default value: 'present'
+
+##### `version`
+
+Data type: `Any`
+
+Version of Java to install, e.g. '7' or '8'. Default values for major and minor versions will be used.
+
+Default value: '8'
+
+##### `version_major`
+
+Data type: `Any`
+
+Major version which should be installed, e.g. '8u101'. Must be used together with version_minor.
+
+Default value: `undef`
+
+##### `version_minor`
+
+Data type: `Any`
+
+Minor version which should be installed, e.g. 'b12'. Must be used together with version_major.
+
+Default value: `undef`
+
+##### `java_se`
+
+Data type: `Any`
+
+Type of Java Standard Edition to install, jdk or jre.
+
+Default value: 'jdk'
+
+##### `oracle_url`
+
+Data type: `Any`
+
+Official Oracle URL to download binaries from.
+
+Default value: 'http://download.oracle.com/otn-pub/java/jdk/'
+
+##### `proxy_server`
+
+Data type: `Any`
+
+Specify a proxy server, with port number if needed. ie: https://example.com:8080. (passed to archive)
+
+Default value: `undef`
+
+##### `proxy_type`
+
+Data type: `Any`
+
+Proxy server type (none|http|https|ftp). (passed to archive)
+
+Default value: `undef`
+
+##### `url`
+
+Data type: `Any`
+
+Full URL, including oracle_url, release_major, release_minor and package_name, to
+download the Oracle java_se installer. Originally present but not used, activated
+to workaround MODULES-5058.
+
+Default value: `undef`
+
+##### `url_hash`
+
+Data type: `Any`
+
+Directory hash used by the download.oracle.com site.  This value is a 32 character string
+which is part of the file URL returned by the JDK download site.
+
+Default value: `undef`
+
+##### `jce`
+
+Data type: `Any`
+
+Install Oracles Java Cryptographic Extensions into the JRE or JDK
+
+Default value: `false`
+
+##### `basedir`
+
+Data type: `Any`
+
+Directory under which the installation will occur. If not set, defaults to
+/usr/lib/jvm for Debian and /usr/java for RedHat.
+
+Default value: `undef`
+
+##### `manage_basedir`
+
+Data type: `Any`
+
+Whether to manage the basedir directory.  Defaults to false.
+Note: /usr/lib/jvm is managed for Debian by default, separate from this parameter.
+
+Default value: `false`
+
+##### `package_type`
+
+Data type: `Any`
+
+Type of installation package for specified version of java_se. java_se 6 comes
+in a few installation package flavors and we need to account for them.
+Optional forced package types: rpm, rpmbin, tar.gz
+
+Default value: `undef`
+
+##### `manage_symlink`
+
+Data type: `Any`
+
+Whether to manage a symlink that points to the installation directory.  Defaults to false.
+
+Default value: `false`
+
+##### `symlink_name`
+
+Data type: `Any`
+
+The name for the optional symlink in the installation directory.
+
+Default value: `undef`
+
diff --git a/manifests/config.pp b/manifests/config.pp
index 623b121d..7f965f37 100644
--- a/manifests/config.pp
+++ b/manifests/config.pp
@@ -1,4 +1,4 @@
-# On Debian systems, if alternatives are set, manually assign them.
+# @api private
 class java::config ( ) {
   case $::osfamily {
     'Debian': {
diff --git a/manifests/init.pp b/manifests/init.pp
index 9b45bf33..f93f1d73 100644
--- a/manifests/init.pp
+++ b/manifests/init.pp
@@ -1,49 +1,40 @@
-# Class: java
+# @summary
+#   This module manages the Java runtime package
 #
-# This module manages the Java runtime package
-#
-# Parameters:
-#
-#  [*distribution*]
+# @param distribution
 #    The java distribution to install. Can be one of "jdk" or "jre",
 #    or other platform-specific options where there are multiple
 #    implementations available (eg: OpenJDK vs Oracle JDK).
 #
-#  [*version*]
+# @param version
 #    The version of java to install. By default, this module simply ensures
 #    that java is present, and does not require a specific version.
 #
-#  [*package*]
+# @param package
 #    The name of the java package. This is configurable in case a non-standard
 #    java package is desired.
 #
-#  [*package_options*]
+# @param package_options
 #    Array of strings to pass installation options to the 'package' Puppet resource.
 #    Options available depend on the 'package' provider for the target OS.
 #
-#  [*java_alternative*]
+# @param java_alternative
 #    The name of the java alternative to use on Debian systems.
 #    "update-java-alternatives -l" will show which choices are available.
 #    If you specify a particular package, you will almost always also
 #    want to specify which java_alternative to choose. If you set
 #    this, you also need to set the path below.
 #
-#  [*java_alternative_path*]
+# @param java_alternative_path
 #    The path to the "java" command on Debian systems. Since the
 #    alternatives system makes it difficult to verify which
 #    alternative is actually enabled, this is required to ensure the
 #    correct JVM is enabled.
 #
-#  [*java_home*]
+# @param java_home
 #    The path to where the JRE is installed. This will be set as an
 #    environment variable.
 #
-# Actions:
-#
-# Requires:
-#
-# Sample Usage:
-#
 class java(
   String $distribution                                              = 'jdk',
   Pattern[/present|installed|latest|^[.+_0-9a-zA-Z:~-]+$/] $version = 'present',
diff --git a/manifests/oracle.pp b/manifests/oracle.pp
index 865cb521..5245c4b9 100644
--- a/manifests/oracle.pp
+++ b/manifests/oracle.pp
@@ -1,112 +1,73 @@
 # Defined Type java::oracle
 #
-# Description
-# Installs Oracle Java. By using this module you agree to the Oracle licensing
-# agreement.
+# @summary
+#   Installs Oracle Java. By using this module you agree to the Oracle licensing
+#   agreement.
 #
 # Install one or more versions of Oracle Java.
 #
-# uses the following to download the package and automatically accept
-# the licensing terms.
+# Uses the following to download the package and automatically accept
+# the licensing terms:
+#```
 # wget --no-cookies --no-check-certificate --header \
 # "Cookie: gpw_e24=http%3A%2F%2Fwww.oracle.com%2F; oraclelicense=accept-securebackup-cookie" \
 # "http://download.oracle.com/otn-pub/java/jdk/8u131-b11/d54c1d3a095b4ff2b6607d096fa80163/jdk-8u131-linux-x64.tar.gz"
+#```
 #
-# Parameters
-# [*version*]
-# Version of Java to install, e.g. '7' or '8'. Default values for major and minor
-# versions will be used.
+# @param ensure
+#   Install or remove the package.
 #
-# [*version_major*]
-# Major version which should be installed, e.g. '8u101'. Must be used together with
-# version_minor.
+# @param version
+#   Version of Java to install, e.g. '7' or '8'. Default values for major and minor versions will be used.
 #
-# [*version_minor*]
-# Minor version which should be installed, e.g. 'b12'. Must be used together with
-# version_major.
+# @param version_major
+#   Major version which should be installed, e.g. '8u101'. Must be used together with version_minor.
 #
-# [*java_se*]
-# Type of Java Standard Edition to install, jdk or jre.
+# @param version_minor
+#   Minor version which should be installed, e.g. 'b12'. Must be used together with version_major.
 #
-# [*ensure*]
-# Install or remove the package.
+# @param java_se
+#   Type of Java Standard Edition to install, jdk or jre.
 #
-# [*oracle_url*]
-# Official Oracle URL to download binaries from.
+# @param oracle_url
+#   Official Oracle URL to download binaries from.
 #
-# [*proxy_server*]
-# Specify a proxy server, with port number if needed. ie: https://example.com:8080. (passed to archive)
+# @param proxy_server
+#   Specify a proxy server, with port number if needed. ie: https://example.com:8080. (passed to archive)
 #
-# [*proxy_type*]
-# Proxy server type (none|http|https|ftp). (passed to archive)
+# @param proxy_type
+#   Proxy server type (none|http|https|ftp). (passed to archive)
 #
-# Variables
-# [*release_major*]
-# Major version release number for java_se. Used to construct download URL.
+# @param url
+#   Full URL, including oracle_url, release_major, release_minor and package_name, to
+#   download the Oracle java_se installer. Originally present but not used, activated
+#   to workaround MODULES-5058.
 #
-# [*release_minor*]
-# Minor version release number for java_se. Used to construct download URL.
+# @param url_hash
+#   Directory hash used by the download.oracle.com site.  This value is a 32 character string
+#   which is part of the file URL returned by the JDK download site.
 #
-# [*install_path*]
-# Base install path for specified version of java_se. Used to determine if java_se
-# has already been installed.
+# @param jce
+#   Install Oracles Java Cryptographic Extensions into the JRE or JDK
 #
-# [*package_type*]
-# Type of installation package for specified version of java_se. java_se 6 comes
-# in a few installation package flavors and we need to account for them.
-# Optional forced package types: rpm, rpmbin, tar.gz
+# @param basedir
+#   Directory under which the installation will occur. If not set, defaults to
+#   /usr/lib/jvm for Debian and /usr/java for RedHat.
 #
-# [*os*]
-# Oracle java_se OS type.
+# @param manage_basedir
+#   Whether to manage the basedir directory.  Defaults to false.
+#   Note: /usr/lib/jvm is managed for Debian by default, separate from this parameter.
 #
-# [*destination*]
-# Destination directory to save java_se installer to.  Usually /tmp on Linux and
-# C:\TEMP on Windows.
+# @param package_type
+#   Type of installation package for specified version of java_se. java_se 6 comes
+#   in a few installation package flavors and we need to account for them.
+#   Optional forced package types: rpm, rpmbin, tar.gz
 #
-# [*creates_path*]
-# Fully qualified path to java_se after it is installed. Used to determine if
-# java_se is already installed.
+# @param manage_symlink
+#   Whether to manage a symlink that points to the installation directory.  Defaults to false.
 #
-# [*arch*]
-# Oracle java_se architecture type.
-#
-# [*package_name*]
-# Name of the java_se installation package to download from Oracle's website.
-#
-# [*install_command*]
-# Installation command used to install Oracle java_se. Installation commands
-# differ by package_type. 'bin' types are installed via shell command. 'rpmbin'
-# types have the rpms extracted and then forcibly installed. 'rpm' types are
-# forcibly installed.
-#
-# [*url*]
-# Full URL, including oracle_url, release_major, release_minor and package_name, to
-# download the Oracle java_se installer. Originally present but not used, activated
-# to workaround MODULES-5058
-#
-# [*url_hash*]
-# Directory hash used by the download.oracle.com site.  This value is a 32 character string
-# which is part of the file URL returned by the JDK download site.
-#
-# [*jce*]
-# Install Oracles Java Cryptographic Extensions into the JRE or JDK
-#
-# [*basedir*]
-# Directory under which the installation will occur. If not set, defaults to
-# /usr/lib/jvm for Debian and /usr/java for RedHat.
-#
-# [*manage_basedir*]
-# Whether to manage the basedir directory.  Defaults to false.
-# Note: /usr/lib/jvm is managed for Debian by default, separate from this parameter.
-#
-# [*manage_symlink*]
-# Whether to manage a symlink that points to the installation directory.  Defaults to false.
-#
-# [*symlink_name*]
-# The name for the optional symlink in the installation directory.
-#
-# ### Author
-# mike@marseglia.org
+# @param symlink_name
+#   The name for the optional symlink in the installation directory.
 #
 define java::oracle (
   $ensure         = 'present',
diff --git a/manifests/params.pp b/manifests/params.pp
index 8da61228..29b66bce 100644
--- a/manifests/params.pp
+++ b/manifests/params.pp
@@ -1,15 +1,9 @@
-# Class: java::params
+# @summary
+#   This class builds a hash of JDK/JRE packages and (for Debian)
+#   alternatives.  For wheezy/precise, we provide Oracle JDK/JRE
+#   options, even though those are not in the package repositories.
 #
-# This class builds a hash of JDK/JRE packages and (for Debian)
-# alternatives.  For wheezy/precise, we provide Oracle JDK/JRE
-# options, even though those are not in the package repositories.
-#
-# For more info on how to package Oracle JDK/JRE, see the Debian wiki:
-# http://wiki.debian.org/JavaPackage
-#
-# Because the alternatives system makes it very difficult to tell
-# which Java alternative is enabled, we hard code the path to bin/java
-# for the config class to test if it is enabled.
+# @api private
 class java::params {
 
   case $::osfamily {