cmd/gomobile: generate package documentation

Change-Id: I2a41cf0f16dcefe87c73ab0a8f02a251c1243157
Reviewed-on: https://go-review.googlesource.com/8121
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>

cmd/gomobile/bind.go

@@ -31,7 +31,7 @@ var cmdBind = &command{
 	run:   runBind,
 	Name:  "bind",
 	Usage: "[package]",
-	Short: "build a shared library for android APK and/or iOS app",
+	Short: "build a shared library for android APK and iOS app",
 	Long: `
 Bind generates language bindings like gobind (golang.org/x/mobile/cmd/gobind)
 for a package and builds a shared library for each platform from the go binding

cmd/gomobile/build.go

@@ -29,8 +29,8 @@ var tmpdir string
 var cmdBuild = &command{
 	run:   runBuild,
 	Name:  "build",
-	Usage: "[package]",
-	Short: "compile android APK and/or iOS app",
+	Usage: "[-o output] [-i] [build flags] [package]",
+	Short: "compile android APK and iOS app",
 	Long: `
 Build compiles and encodes the app named by the import path.
 

cmd/gomobile/doc.go

@@ -0,0 +1,134 @@
+// Copyright 2015 The Go Authors.  All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// DO NOT EDIT. GENERATED BY 'gomobile help documentation'.
+
+/*
+Gomobile is a tool for building and running mobile apps written in Go.
+
+Installation:
+
+	$ go get golang.org/x/mobile/cmd/gomobile
+	$ gomobile init
+
+	Note that until Go 1.5 is released, you must compile Go from
+	tip. For details see https://golang.org/doc/install/source.
+	The minimum process is:
+
+	$ git clone https://go.googlesource.com/go
+	$ cd go/src
+	$ ./all.bash
+
+Usage:
+
+	gomobile command [arguments]
+
+Commands:
+
+	bind        build a shared library for android APK and iOS app
+	build       compile android APK and iOS app
+	init        install android compiler toolchain
+	install     compile android APK and iOS app and install on device
+
+Use 'gomobile help [command]' for more information about that command.
+
+NOTE: iOS support is not ready yet.
+
+
+Build a shared library for android APK and iOS app
+
+Usage:
+
+	gomobile bind [package]
+
+Bind generates language bindings like gobind (golang.org/x/mobile/cmd/gobind)
+for a package and builds a shared library for each platform from the go binding
+code.
+
+The -outdir flag specifies the output directory and is required.
+
+For Android, the bind command will place the generated Java API stubs and the
+compiled shared libraries in the android subdirectory of the following layout.
+
+<outdir>/android
+  libs/
+     armeabi-v7a/libgojni.so
+     ...
+  src/main/java/go/
+	Seq.java
+	Go.java
+        mypackage/Mypackage.java
+
+The -v flag provides verbose output, including the list of packages built.
+
+These build flags are shared by the build command.
+For documentation, see 'go help build':
+	-a
+	-i
+	-n
+	-x
+	-tags 'tag list'
+
+
+Compile android APK and iOS app
+
+Usage:
+
+	gomobile build [-o output] [-i] [build flags] [package]
+
+Build compiles and encodes the app named by the import path.
+
+The named package must define a main function.
+
+If an AndroidManifest.xml is defined in the package directory, it is
+added to the APK file. Otherwise, a default manifest is generated.
+
+If the package directory contains an assets subdirectory, its contents
+are copied into the APK file.
+
+The -o flag specifies the output file name. If not specified, the
+output file name depends on the package built. The output file must end
+in '.apk'.
+
+The -v flag provides verbose output, including the list of packages built.
+
+These build flags are shared by the build, install, and test commands.
+For documentation, see 'go help build':
+	-a
+	-i
+	-n
+	-x
+	-tags 'tag list'
+
+
+Install android compiler toolchain
+
+Usage:
+
+	gomobile init [-u]
+
+Init downloads and installs the Android C++ compiler toolchain.
+
+The toolchain is installed in $GOPATH/pkg/gomobile.
+If the Android C++ compiler toolchain already exists in the path,
+it skips download and uses the existing toolchain.
+
+The -u option forces download and installation of the new toolchain
+even when the toolchain exists.
+
+
+Compile android APK and iOS app and install on device
+
+Usage:
+
+	gomobile install [package]
+
+Install compiles and installs the app named by the import path on the
+attached mobile device.
+
+This command requires the 'adb' tool on the PATH.
+
+See the build command help for common flags and common behavior.
+*/
+package main

cmd/gomobile/init.go

@@ -49,6 +49,7 @@ func init() {
 var cmdInit = &command{
 	run:   runInit,
 	Name:  "init",
+	Usage: "[-u]",
 	Short: "install android compiler toolchain",
 	Long: `
 Init downloads and installs the Android C++ compiler toolchain.

cmd/gomobile/install.go

@@ -14,7 +14,7 @@ var cmdInstall = &command{
 	run:   runInstall,
 	Name:  "install",
 	Usage: "[package]",
-	Short: "compile android APK and/or iOS app and install on device",
+	Short: "compile android APK and iOS app and install on device",
 	Long: `
 Install compiles and installs the app named by the import path on the
 attached mobile device.

cmd/gomobile/main.go

@@ -2,21 +2,22 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-/*
-Gomobile is a tool for building and running mobile apps written in Go.
-
-The tool is under development and not ready for use.
-*/
 package main
 
+//go:generate gomobile help documentation doc.go
+
 import (
 	"bufio"
+	"bytes"
 	"flag"
 	"fmt"
 	"html/template"
 	"io"
+	"io/ioutil"
 	"log"
 	"os"
+	"unicode"
+	"unicode/utf8"
 )
 
 func printUsage(w io.Writer) {
@@ -44,6 +45,10 @@ func main() {
 	}
 
 	if args[0] == "help" {
+		if len(args) == 3 && args[1] == "documentation" {
+			helpDocumentation(args[2])
+			return
+		}
 		help(args[1:])
 		return
 	}
@@ -91,6 +96,37 @@ func help(args []string) {
 	os.Exit(2)
 }
 
+const documentationHeader = `// Copyright 2015 The Go Authors.  All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// DO NOT EDIT. GENERATED BY 'gomobile help documentation'.
+`
+
+func helpDocumentation(path string) {
+	w := new(bytes.Buffer)
+	w.WriteString(documentationHeader)
+	w.WriteString("\n/*\n")
+	if err := usageTmpl.Execute(w, commands); err != nil {
+		log.Fatal(err)
+	}
+
+	for _, cmd := range commands {
+		r, rlen := utf8.DecodeRuneInString(cmd.Short)
+		w.WriteString("\n\n")
+		w.WriteRune(unicode.ToUpper(r))
+		w.WriteString(cmd.Short[rlen:])
+		w.WriteString("\n\nUsage:\n\n\tgomobile " + cmd.Name + " " + cmd.Usage + "\n")
+		w.WriteString(cmd.Long)
+	}
+
+	w.WriteString("*/\npackage main\n")
+
+	if err := ioutil.WriteFile(path, w.Bytes(), 0666); err != nil {
+		log.Fatal(err)
+	}
+}
+
 var commands = []*command{
 	// TODO(crawshaw): cmdRun
 	cmdBind,
@@ -113,7 +149,20 @@ func (cmd *command) usage() {
 }
 
 var usageTmpl = template.Must(template.New("usage").Parse(
-	`Gomobile is a tool for building Android and iOS Go apps.
+	`Gomobile is a tool for building and running mobile apps written in Go.
+
+Installation:
+
+	$ go get golang.org/x/mobile/cmd/gomobile
+	$ gomobile init
+
+	Note that until Go 1.5 is released, you must compile Go from
+	tip. For details see https://golang.org/doc/install/source.
+	The minimum process is:
+
+	$ git clone https://go.googlesource.com/go
+	$ cd go/src
+	$ ./all.bash
 
 Usage:
 
@@ -124,4 +173,6 @@ Commands:
 	{{.Name | printf "%-11s"}} {{.Short}}{{end}}
 
 Use 'gomobile help [command]' for more information about that command.
+
+NOTE: iOS support is not ready yet.
 `))