diff --git a/kotlin/BUILD b/kotlin/BUILD
index b6a5992..f8db35a 100644
--- a/kotlin/BUILD
+++ b/kotlin/BUILD
@@ -13,11 +13,7 @@
 # limitations under the License.
 package(default_visibility = ["//visibility:public"])
 
-load("//kotlin/internal:toolchains.bzl", "kt_toolchain_ide_info")
-
 toolchain_type(
     name = "kt_toolchain_type",
     visibility = ["//visibility:public"],
 )
-
-kt_toolchain_ide_info(name = "kt_toolchain_ide_info")
diff --git a/kotlin/internal/jvm/jvm.bzl b/kotlin/internal/jvm/jvm.bzl
index 55f8b9e..d155c1b 100644
--- a/kotlin/internal/jvm/jvm.bzl
+++ b/kotlin/internal/jvm/jvm.bzl
@@ -89,20 +89,12 @@
 )
 ```
 """
-# This file is the main import -- it shouldn't grow out of hand the reason it contains so much allready is due to the limitations of skydoc.
 
-########################################################################################################################
-# Common Definitions
-########################################################################################################################
 load("//kotlin/internal:defs.bzl", _KtJvmInfo = "KtJvmInfo", _TOOLCHAIN_TYPE = "TOOLCHAIN_TYPE")
-
-# struct can't be used till skydoc is removed
 load(
     "//kotlin/internal/jvm:plugins.bzl",
     _kt_jvm_plugin_aspect = "kt_jvm_plugin_aspect",
 )
-
-# struct can't be used till skydoc is removed
 load(
     "//kotlin/internal/jvm:impl.bzl",
     _kt_jvm_binary_impl = "kt_jvm_binary_impl",
@@ -111,17 +103,7 @@
     _kt_jvm_library_impl = "kt_jvm_library_impl",
 )
 
-########################################################################################################################
-# Rule Attributes
-########################################################################################################################
 _implicit_deps = {
-    "_kotlin_toolchain": attr.label_list(
-        default = [
-            Label("@io_bazel_rules_kotlin//kotlin:kt_toolchain_ide_info"),
-        ],
-        cfg = "host",
-        allow_files = False,
-    ),
     "_singlejar": attr.label(
         executable = True,
         cfg = "host",
@@ -146,26 +128,46 @@
     ),
 }
 
-_common_attr = dict(_implicit_deps.items() + {
+_common_attr = _implicit_deps + {
     "srcs": attr.label_list(
+        doc = """The list of source files that are processed to create the target, this can contain both Java and Kotlin
+        files. Java analysis occurs first so Kotlin classes may depend on Java classes in the same compilation unit.""",
         default = [],
         allow_files = [".srcjar", ".kt", ".java"],
     ),
     "deps": attr.label_list(
+        doc = """A list of dependencies of this rule.See general comments about `deps` at
+        [Attributes common to all build rules](https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes).""",
         aspects = [_kt_jvm_plugin_aspect],
         providers = [
             [JavaInfo],
         ],
         allow_files = False,
     ),
-    "runtime_deps": attr.label_list(default = [], allow_files = False),
+    "runtime_deps": attr.label_list(
+        doc = """Libraries to make available to the final binary or test at runtime only. Like ordinary deps, these will
+        appear on the runtime classpath, but unlike them, not on the compile-time classpath.""",
+        default = [],
+        allow_files = False,
+    ),
     "resources": attr.label_list(
+        doc = """A list of files that should be include in a Java jar.""",
         default = [],
         allow_files = True,
     ),
-    "resource_strip_prefix": attr.string(default = ""),
-    "resource_jars": attr.label_list(default = []),
+    "resource_strip_prefix": attr.string(
+        doc = """The path prefix to strip from Java resources, files residing under common prefix such as
+        `src/main/resources` or `src/test/resources` will have stripping applied by convention.""",
+        default = "",
+    ),
+    "resource_jars": attr.label_list(
+        doc = """Set of archives containing Java resources. If specified, the contents of these jars are merged into
+        the output jar.""",
+        default = [],
+    ),
     "data": attr.label_list(
+        doc = """The list of files needed by this rule at runtime. See general comments about `data` at
+        [Attributes common to all build rules](https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes).""",
         allow_files = True,
         cfg = "data",
     ),
@@ -174,19 +176,21 @@
         aspects = [_kt_jvm_plugin_aspect],
     ),
     "module_name": attr.string(
+        doc = """The name of the module, if not provided the module name is derived from the label. --e.g.,
+        `//some/package/path:label_name` is translated to
+        `some_package_path-label_name`.""",
         mandatory = False,
     ),
-}.items())
+}
 
-_runnable_common_attr = dict(_common_attr.items() + {
+_runnable_common_attr = _common_attr + {
     "jvm_flags": attr.string_list(
+        doc = """A list of flags to embed in the wrapper script generated for running this binary. Note: does not yet
+        support make variable substitution.""",
         default = [],
     ),
-}.items())
+}
 
-########################################################################################################################
-# Outputs: All the outputs produced by the various rules are modelled here.
-########################################################################################################################
 _common_outputs = dict(
     jar = "%{name}.jar",
     jdeps = "%{name}.jdeps",
@@ -195,108 +199,129 @@
     srcjar = "%{name}-sources.jar",
 )
 
-_binary_outputs = dict(_common_outputs.items() + {
-}.items())
-
-########################################################################################################################
-# Simple Rules:
-########################################################################################################################
 kt_jvm_library = rule(
-    attrs = dict(_common_attr.items() + {
-        "exports": attr.label_list(default = [], providers = [JavaInfo]),
-        "neverlink": attr.bool(default = False),
-    }.items()),
+    doc = """This rule compiles and links Kotlin and Java sources into a .jar file.""",
+    attrs = _common_attr + {
+        "exports": attr.label_list(
+            doc = """Exported libraries.
+
+            Deps listed here will be made available to other rules, as if the parents explicitly depended on
+            these deps. This is not true for regular (non-exported) deps.""",
+            default = [],
+            providers = [JavaInfo],
+        ),
+        "neverlink": attr.bool(
+            doc = """If true only use this library for compilation and not at runtime.""",
+            default = False,
+        ),
+    },
     outputs = _common_outputs,
     toolchains = [_TOOLCHAIN_TYPE],
     implementation = _kt_jvm_library_impl,
     provides = [JavaInfo, _KtJvmInfo],
 )
 
-"""This rule compiles and links Kotlin and Java sources into a .jar file.
-Args:
-  srcs: The list of source files that are processed to create the target, this can contain both Java and Kotlin files. Java analysis occurs first so Kotlin
-    classes may depend on Java classes in the same compilation unit.
-  exports: Exported libraries.
-
-    Deps listed here will be made available to other rules, as if the parents explicitly depended on these deps.
-    This is not true for regular (non-exported) deps.
-  resources: A list of data files to include in a Java jar.
-  resource_strip_prefix: The path prefix to strip from Java resources, files residing under common prefix such as `src/main/resources` or `src/test/resources`
-    will have stripping applied by convention.
-  resource_jars: Set of archives containing Java resources. If specified, the contents of these jars are merged into the output jar.
-  runtime_deps: Libraries to make available to the final binary or test at runtime only. Like ordinary deps, these will appear on the runtime classpath, but
-    unlike them, not on the compile-time classpath.
-  data: The list of files needed by this rule at runtime. See general comments about `data` at [Attributes common to all build rules](https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes).
-  deps: A list of dependencies of this rule.See general comments about `deps` at [Attributes common to all build rules](https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes).
-  module_name: The name of the module, if not provided the module name is derived from the label. --e.g., `//some/package/path:label_name` is translated to
-    `some_package_path-label_name`.
-  neverlink: If true only use this library for compilation and not at runtime.
-"""
-
 kt_jvm_binary = rule(
+    doc = """Builds a Java archive ("jar file"), plus a wrapper shell script with the same name as the rule. The wrapper
+    shell script uses a classpath that includes, among other things, a jar file for each library on which the binary
+    depends.
+
+    **Note:** This rule does not have all of the features found in [`java_binary`](https://docs.bazel.build/versions/master/be/java.html#java_binary).
+    It is appropriate for building workspace utilities. `java_binary` should be preferred for release artefacts.
+    """,
     attrs = dict(_runnable_common_attr.items() + {
-        "main_class": attr.string(mandatory = True),
+        "main_class": attr.string(
+            doc = """Name of class with main() method to use as entry point.""",
+            mandatory = True,
+        ),
     }.items()),
     executable = True,
-    outputs = _binary_outputs,
+    outputs = _common_outputs,
     toolchains = [_TOOLCHAIN_TYPE],
     implementation = _kt_jvm_binary_impl,
 )
 
-"""Builds a Java archive ("jar file"), plus a wrapper shell script with the same name as the rule. The wrapper shell script uses a classpath that includes,
-among other things, a jar file for each library on which the binary depends.
-
-**Note:** This rule does not have all of the features found in [`java_binary`](https://docs.bazel.build/versions/master/be/java.html#java_binary). It is
-appropriate for building workspace utilities. `java_binary` should be preferred for release artefacts.
-
-Args:
-  main_class: Name of class with main() method to use as entry point.
-  jvm_flags: A list of flags to embed in the wrapper script generated for running this binary. Note: does not yet support make variable substitution.
-"""
-
 kt_jvm_test = rule(
-    attrs = dict(_runnable_common_attr.items() + {
+    doc = """Setup a simple kotlin_test.
+
+    **Notes:**
+    * The kotlin test library is not added implicitly, it is available with the label
+    `@com_github_jetbrains_kotlin//:kotlin-test`.
+    """,
+    attrs = _runnable_common_attr + {
         "_bazel_test_runner": attr.label(
             default = Label("@bazel_tools//tools/jdk:TestRunner_deploy.jar"),
             allow_files = True,
         ),
         "friends": attr.label_list(
+            doc = """A single Kotlin dep which allows the test code access to internal members. Currently uses the output
+            jar of the module -- i.e., exported deps won't be included.""",
             default = [],
             providers = [JavaInfo, _KtJvmInfo],
         ),
-        "test_class": attr.string(),
+        "test_class": attr.string(
+            doc = "The Java class to be loaded by the test runner.",
+            default = "",
+        ),
         "main_class": attr.string(default = "com.google.testing.junit.runner.BazelTestRunner"),
-    }.items()),
+    },
     executable = True,
-    outputs = _binary_outputs,
+    outputs = _common_outputs,
     test = True,
     toolchains = [_TOOLCHAIN_TYPE],
     implementation = _kt_jvm_junit_test_impl,
 )
 
-"""Setup a simple kotlin_test.
-
-**Notes:**
-* The kotlin test library is not added implicitly, it is available with the label `@com_github_jetbrains_kotlin//:kotlin-test`.
-
-Args:
-  test_class: The Java class to be loaded by the test runner.
-  friends: A single Kotlin dep which allows the test code access to internal members. Currently uses the output jar of
-    the module -- i.e., exported deps won't be included.
-"""
-
 kt_jvm_import = rule(
+    doc = """Import Kotlin jars.
+
+     ## examples
+
+     ```bzl
+     # Old style usage -- reference file groups, do not used this.
+     kt_jvm_import(
+         name = "kodein",
+         jars = [
+             "@com_github_salomonbrys_kodein_kodein//jar:file",
+             "@com_github_salomonbrys_kodein_kodein_core//jar:file"
+         ]
+     )
+
+     # This style will pull in the transitive runtime dependencies of the targets as well.
+     kt_jvm_import(
+         name = "kodein",
+         jars = [
+             "@com_github_salomonbrys_kodein_kodein//jar",
+             "@com_github_salomonbrys_kodein_kodein_core//jar"
+         ]
+     )
+
+     # Import a single kotlin jar.
+     kt_jvm_import(
+         name = "kotlin-runtime",
+         jars = ["lib/kotlin-runtime.jar"],
+         srcjar = "lib/kotlin-runtime-sources.jar"
+     )
+     ```
+    """,
     attrs = {
         "jars": attr.label_list(
+            doc = """The jars listed here are equavalent to an export attribute. The label should be either to a single
+            class jar, or multiple filegroup labels. When the labels is a file_provider it should follow the conventions
+            used in repositories generated by the maven_jar rule  --i.e., the rule expects a file_provider with a single
+            class jar and a single source jar. a source jar is recognized by the suffix `-sources.jar`.""",
             allow_files = True,
             mandatory = True,
             cfg = "target",
         ),
         "srcjar": attr.label(
+            doc = """The sources for the class jar. This should generally be provided especially when importing a single
+            jar.""",
             allow_single_file = True,
             cfg = "target",
         ),
         "runtime_deps": attr.label_list(
+            doc = """Additional runtime deps.""",
             default = [],
             mandatory = False,
             providers = [JavaInfo],
@@ -305,52 +330,3 @@
     implementation = _kt_jvm_import_impl,
     provides = [JavaInfo, _KtJvmInfo],
 )
-
-# The pairing of src and class is used by intellij to attatch sources, this is picked up via the kt provider attribute.
-#
-# once current format and semantics are finalized add runtime_deps, exports, data, neverlink, testonly.
-#   * runtime_deps should accept JavaInfo's (this includes KotlinInfo) and maven_jar filegroups.
-#   * exports should only accept JavaInfo's (this include KotlinInfo) but not filegroup. The jars attribute takes care of importing the jars without generating
-#     ijars.
-"""(experimental) Import Kotlin jars.
-
-**Status:** This rule is not a counterpart to `java_import`. The current purpose for this rule is to import a kotlin jar without creating ijars. It will
-eventually [be replaced](https://github.com/bazelbuild/rules_kotlin/issues/4) with `java_import`. If there is a need for expanding this rule we can instead
-create a utility macro that delegates to this.
-
-## examples
-
-```bzl
-# Old style usage -- reference file groups, do not used this.
-kt_jvm_import(
-    name = "kodein",
-    jars = [
-        "@com_github_salomonbrys_kodein_kodein//jar:file",
-        "@com_github_salomonbrys_kodein_kodein_core//jar:file"
-    ]
-)
-
-# This style will pull in the transitive runtime dependencies of the targets as well.
-kt_jvm_import(
-    name = "kodein",
-    jars = [
-        "@com_github_salomonbrys_kodein_kodein//jar",
-        "@com_github_salomonbrys_kodein_kodein_core//jar"
-    ]
-)
-
-# Import a single kotlin jar.
-kt_jvm_import(
-    name = "kotlin-runtime",
-    jars = ["lib/kotlin-runtime.jar"],
-    srcjar = "lib/kotlin-runtime-sources.jar"
-)
-```
-
-Args:
-  jars: The jars listed here are equavalent to an export attribute. The label should be either to a single class jar, or multiple filegroup labels. When the
-    labels is a file_provider it should follow the conventions used in repositories generated by the maven_jar rule  --i.e., the rule expects a file_provider
-    with a single class jar and a single source jar. a source jar is recognized by the suffix `-sources.jar`.
-  srcjar: The sources for the class jar. This should be set when importing a single class jar.
-  runtime_deps: Additional runtime deps.
-"""
diff --git a/kotlin/internal/toolchains.bzl b/kotlin/internal/toolchains.bzl
index aeae3e8..32e0477 100644
--- a/kotlin/internal/toolchains.bzl
+++ b/kotlin/internal/toolchains.bzl
@@ -38,73 +38,6 @@
 ```
 """
 
-# The toolchain rules are not made private, at least the jvm ones so that they may be introspected in Intelij.
-_common_attrs = {
-    "kotlin_home": attr.label(
-        default = Label("@" + _KT_COMPILER_REPO + "//:home"),
-        allow_files = True,
-    ),
-    "kotlinbuilder": attr.label(
-        default = Label("//kotlin/builder"),
-        executable = True,
-        allow_files = True,
-        cfg = "host",
-    ),
-    "language_version": attr.string(
-        default = "1.2",
-        values = [
-            "1.1",
-            "1.2",
-        ],
-    ),
-    "api_version": attr.string(
-        default = "1.2",
-        values = [
-            "1.1",
-            "1.2",
-        ],
-    ),
-    "debug": attr.string_list(
-        allow_empty = True,
-        doc = """Debugging tags passed to the builder. Two tags are supported. `timings` will cause the builder to print
-timing information. `trace` will cause the builder to print tracing messages. These tags can be enabled via the default
-toolchain via the defines `kt_timings=1` and `kt_trace=1`. The tags may also be picked up via the `tags` attribute
-defined directly on the rules.""",
-    ),
-    "coroutines": attr.string(
-        default = "enable",
-        values = [
-            "enable",
-            "warn",
-            "error",
-        ],
-    ),
-}
-
-_kt_jvm_attrs = dict(_common_attrs.items() + {
-    "jvm_runtime": attr.label(
-        default = Label("@" + _KT_COMPILER_REPO + "//:kotlin-runtime"),
-        providers = [JavaInfo],
-        cfg = "target",
-    ),
-    "jvm_stdlibs": attr.label_list(
-        default = [
-            Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib"),
-            Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib-jdk7"),
-            Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib-jdk8"),
-        ],
-        providers = [JavaInfo],
-        cfg = "target",
-    ),
-    "jvm_target": attr.string(
-        default = "1.8",
-        values = [
-            "1.6",
-            "1.8",
-        ],
-    ),
-}.items())
-
 def _kotlin_toolchain_impl(ctx):
     toolchain = dict(
         label = _common.restore_label(ctx.label),
@@ -126,19 +59,84 @@
     ]
 
 kt_toolchain = rule(
-    attrs = _kt_jvm_attrs,
+    doc = """The kotlin toolchain. This should not be created directly `define_kt_toolchain` should be used. The
+    rules themselves define the toolchain using that macro.""",
+    attrs = {
+        "kotlin_home": attr.label(
+            doc = "the filegroup defining the kotlin home",
+            default = Label("@" + _KT_COMPILER_REPO + "//:home"),
+            allow_files = True,
+        ),
+        "kotlinbuilder": attr.label(
+            doc = "the kotlin builder executable",
+            default = Label("//kotlin/builder"),
+            executable = True,
+            allow_files = True,
+            cfg = "host",
+        ),
+        "language_version": attr.string(
+            doc = "this is the -languag_version flag [see](https://kotlinlang.org/docs/reference/compatibility.html)",
+            default = "1.2",
+            values = [
+                "1.1",
+                "1.2",
+            ],
+        ),
+        "api_version": attr.string(
+            doc = "this is the -api_version flag [see](https://kotlinlang.org/docs/reference/compatibility.html).",
+            default = "1.2",
+            values = [
+                "1.1",
+                "1.2",
+            ],
+        ),
+        "debug": attr.string_list(
+            doc = """Debugging tags passed to the builder. Two tags are supported. `timings` will cause the builder to
+            print timing information. `trace` will cause the builder to print tracing messages. These tags can be
+            enabled via the defines `kt_timings=1` and `kt_trace=1`. These can also be enabled on a per target bases by
+            using `tags` attribute defined directly on the rules.""",
+            allow_empty = True,
+        ),
+        "coroutines": attr.string(
+            doc = "the -Xcoroutines flag, enabled by default as it's considered production ready 1.2.0 onward.",
+            default = "enable",
+            values = [
+                "enable",
+                "warn",
+                "error",
+            ],
+        ),
+        "jvm_runtime": attr.label(
+            doc = "The implicit jvm runtime libraries. This is internal.",
+            default = Label("@" + _KT_COMPILER_REPO + "//:kotlin-runtime"),
+            providers = [JavaInfo],
+            cfg = "target",
+        ),
+        "jvm_stdlibs": attr.label_list(
+            doc = "The jvm stdlibs. This is internal.",
+            default = [
+                Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib"),
+                Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib-jdk7"),
+                # JDK8 is being added blindly but I think we will probably not support bytecode levels 1.6 when the
+                # repo stabelizes so this should be fine.
+                Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib-jdk8"),
+            ],
+            providers = [JavaInfo],
+            cfg = "target",
+        ),
+        "jvm_target": attr.string(
+            doc = "the -jvm_target flag. This is only tested at 1.8.",
+            default = "1.8",
+            values = [
+                "1.6",
+                "1.8",
+            ],
+        ),
+    },
     implementation = _kotlin_toolchain_impl,
     provides = [platform_common.ToolchainInfo],
 )
 
-"""The kotlin jvm toolchain
-Args:
-  language_version: the -languag_version flag [see](https://kotlinlang.org/docs/reference/compatibility.html).
-  api_version: the -api_version flag [see](https://kotlinlang.org/docs/reference/compatibility.html).
-  jvm_target: the -jvm_target flag.
-  coroutines: the -Xcoroutines flag, enabled by default as it's considered production ready 1.2.0 onward.
-"""
-
 def kt_register_toolchains():
     """This macro registers all of the default toolchains."""
     native.register_toolchains("@io_bazel_rules_kotlin//kotlin/internal:default_toolchain")
@@ -169,25 +167,3 @@
         toolchain = impl_name,
         visibility = ["//visibility:public"],
     )
-
-def _kt_toolchain_ide_info_impl(ctx):
-    tc = ctx.toolchains[_TOOLCHAIN_TYPE]
-    info = struct(
-        label = tc.label,
-        common = struct(
-            language_version = tc.language_version,
-            api_version = tc.api_version,
-            coroutines = tc.coroutines,
-        ),
-        jvm = struct(
-            jvm_target = tc.jvm_target,
-        ),
-    )
-    ctx.actions.write(ctx.outputs.ide_info, info.to_json())
-    return [DefaultInfo(files = depset([ctx.outputs.ide_info]))]
-
-kt_toolchain_ide_info = rule(
-    outputs = {"ide_info": "kt_toolchain_ide_info.json"},
-    toolchains = [_TOOLCHAIN_TYPE],
-    implementation = _kt_toolchain_ide_info_impl,
-)