Add bucklets documentation

Change-Id: I7d491127cd93e7b28b02bd8070a8deaf49de48b4

java7.bucklet

diff --git a/java7.bucklet b/java7.bucklet
index 488fba4..c7996ca 100644
--- a/java7.bucklet
+++ b/java7.bucklet
@@ -1,4 +1,25 @@
-# see https://github.com/facebook/buck/pull/67
+# Current Buck version lacks support to overwrite Java version
+# in .buckconfig file, under Java section, e. g.:
+#
+# [java]
+#   src_roots = java, resources
+#   source = 7
+#   target = 7
+#
+# Instead, the documentaion suggests to provide Java version in
+# each and every java_library() call.
+#
+# This bucklet overwrites the definition of original java_library
+# and java_test rules.
+#
+# Example: this bucklet must be used in .buckconfig file, under
+# include section to ensure, that this file is seen before others:
+#
+# [buildfile]
+#   includes = //bucklets/java7.bucklet
+#
+# @See https://github.com/facebook/buck/pull/67
+#
 original_java_library = java_library
 def java_library(
     name,

java8.bucklet

diff --git a/java8.bucklet b/java8.bucklet
index 1fb22aa..d7ebe06 100644
--- a/java8.bucklet
+++ b/java8.bucklet
@@ -1,4 +1,25 @@
-# see https://github.com/facebook/buck/pull/67
+# Current Buck version lacks support to overwrite Java version
+# in .buckconfig file, under Java section, e. g.:
+#
+# [java]
+#   src_roots = java, resources
+#   source = 8
+#   target = 8
+#
+# Instead, the documentaion suggests to provide Java version in
+# each and every java_library() call.
+#
+# This bucklet overwrites the definition of original java_library
+# and java_test rules.
+#
+# Example: this bucklet must be used in .buckconfig file, under
+# include section to ensure, that this file is seen before others:
+#
+# [buildfile]
+#   includes = //bucklets/java8.bucklet
+#
+# @See https://github.com/facebook/buck/pull/67
+#
 original_java_library = java_library
 def java_library(
     name,

java_doc.bucklet

diff --git a/java_doc.bucklet b/java_doc.bucklet
index 8df3f85..426ef45 100644
--- a/java_doc.bucklet
+++ b/java_doc.bucklet
@@ -1,3 +1,17 @@
+# This bucklet simplifies creation of Javadocs
+#
+# Example:
+#
+# java_doc(
+#   name = 'javadoc',
+#   title = 'Gitiles API Documentation',
+#   pkg = 'com.google.gitiles',
+#   paths = ['gitiles-servlet/src/main/java'],
+#   srcs = glob([n + '**/*.java' for n in SRCS]),
+#   deps = DEPS,
+#   visibility = ['PUBLIC'],
+# )
+#
 def java_doc(
     name,
     title,

java_library2.bucklet

diff --git a/java_library2.bucklet b/java_library2.bucklet
index 8fe78e8..8bfc5ab 100644
--- a/java_library2.bucklet
+++ b/java_library2.bucklet
@@ -1,7 +1,20 @@
 # Compiles a Java library with additional compile-time dependencies
 # that do not show up as transitive dependencies to java_library()
 # or java_binary() rule that depends on this library.
-# work around for: https://github.com/facebook/buck/issues/63
+#
+# Example: servlet library needs to be compiled against servlet API
+# but this dependency must not become a transitive dependency.
+#
+# java_library2(
+#   name = 'gitiles-servlet',
+#   srcs = SRCS,
+#   resources = RSRC,
+#   deps = DEPS,
+#   compile_deps = ['//lib:servlet-api'],
+#   visibility = ['PUBLIC'],
+# )
+# @See: https://github.com/facebook/buck/issues/63
+#
 def java_library2(
     name,
     srcs = [],

java_sources.bucklet

diff --git a/java_sources.bucklet b/java_sources.bucklet
index 0b3974e..b2c6a19 100644
--- a/java_sources.bucklet
+++ b/java_sources.bucklet
@@ -1,3 +1,13 @@
+# This bucklet simplifies creation of Java source archives
+#
+# Example:
+#
+# java_sources(
+#   name = 'src',
+#   srcs = SRCS + RSRC,
+#   visibility = ['PUBLIC'],
+# )
+#
 def java_sources(
     name,
     srcs,

local_jar.bucklet

diff --git a/local_jar.bucklet b/local_jar.bucklet
index 8131daa..6e06ce9 100644
--- a/local_jar.bucklet
+++ b/local_jar.bucklet
@@ -8,17 +8,19 @@
 # local Maven repository and fetching it again from there out of the picture,
 # `local_jar()` method is used:
 #
+# Example:
+#
 # local_jar(
 #   name = 'jgit',
 #   jar = '/home/<user>/projects/jgit/org.eclipse.jgit/target/org.eclipse.jgit-3.3.0-SNAPSHOT.jar',
-#   src = '/home/<user>/projects/jgit/org.eclipse.jgit/target/org.eclipse.jgit-3.3.0-SNAPSHOT-sources.jar',
+#   src_jar = '/home/<user>/projects/jgit/org.eclipse.jgit/target/org.eclipse.jgit-3.3.0-SNAPSHOT-sources.jar',
 #   deps = [':ewah']
 # )
-
+#
 def local_jar(
     name,
     jar,
-    src = None,
+    src_jar = None,
     deps = [],
     visibility = ['PUBLIC']):
   binjar = name + '.jar'
@@ -27,10 +29,10 @@
     name = name + '__local_bin',
     cmd = 'ln -s %s $OUT' % jar,
     out = binjar)
-  if src:
+  if src_jar:
     genrule(
       name = name + '__local_src',
-      cmd = 'ln -s %s $OUT' % src,
+      cmd = 'ln -s %s $OUT' % src_jar,
       out = srcjar)
     prebuilt_jar(
       name = name + '_src',

maven_jar.bucklet

diff --git a/maven_jar.bucklet b/maven_jar.bucklet
index 19a06f9..b5c6335 100644
--- a/maven_jar.bucklet
+++ b/maven_jar.bucklet
@@ -1,6 +1,32 @@
 #
 # Fetch artifacts from Maven repository
-# see: https://github.com/facebook/buck/issues/64
+#
+# name: (required) The name of the rule.
+# id: (required) Maven group id, artifact id and version in the form: g:a:v
+# exclude: (defaults to []) Rules to exlude from resulting maven JAR
+# exclude_java_sources: (default to False) should java source be included
+# unsign: (default to False): should this archive be unsigned
+# deps: (defaults to []) Rules (usually other java_library rules) that are
+#        included as transitive dependency of this Maven JAR
+# exported_deps: (defaults to []) Whether or not depending on this rule should
+#        also transitively pull in all of its dependencies.
+# sha1: SHA-1 of binary artifact
+# bin_sha1: SHA-1 of binary artifact
+# src_sha1: SHA-1 of src artifact
+# repository: (default to MAVEN_CENTRAL) repository name
+# attach_source: (default to True): should the sources be fetched
+# visibility (defaults to ['PUBLIC']) List of build target patterns that
+# identify the build rules that can include this rule in its deps.
+#
+# Example:
+#
+# maven_jar(
+#   name = 'guava',
+#   id = 'com.google.guava:guava:16.0',
+#   sha1 = 'aca09d2e5e8416bf91550e72281958e35460be52',
+# )
+#
+# @See: https://github.com/facebook/buck/issues/64
 #
 
 GERRIT = 'GERRIT:'

maven_package.bucklet

diff --git a/maven_package.bucklet b/maven_package.bucklet
index 0e865b6..8bd6720 100644
--- a/maven_package.bucklet
+++ b/maven_package.bucklet
@@ -1,17 +1,16 @@
-# Copyright (C) 2013 The Android Open Source Project
+# Install and deploy artifacts into local and remote Maven repositories
 #
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
+# Example:
 #
-# http://www.apache.org/licenses/LICENSE-2.0
+# maven_package(
+#   repository = 'gerrit-api-repository',
+#   url = 'gs://gerrit-api/release',
+#   version = '1.0',
+#   jar = {'gitiles-servlet': '//gitiles-servlet:servlet'},
+#   src = {'gitiles-servlet': '//gitiles-servlet:src'},
+#   doc = {'gitiles-servlet': '//gitiles-servlet:javadoc'},
+# )
 #
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
 def maven_package(
     version,
     repository = None,

war.bucklet

diff --git a/war.bucklet b/war.bucklet
index 2987e05..8341e2d 100644
--- a/war.bucklet
+++ b/war.bucklet
@@ -1,3 +1,16 @@
+# This bucklet simplifies creation of war archives.
+#
+# Example:
+#
+# war(
+#   name = 'gitiles',
+#   libs = ['//gitiles-servlet:servlet'],
+#   context = [
+#     ':recourses.zip',
+#   ],
+#   visibility = ['PUBLIC']
+# )
+#
 def war(
     name,
     libs = [],