From 50251ab2546a46ac6855f4627ba0247d44294da9 Mon Sep 17 00:00:00 2001
From: Eric Seidel <eseidel@google.com>
Date: Tue, 4 Aug 2015 16:13:58 -0700
Subject: [PATCH] Add a few bits of documentation to package:sky

I can't really make further progress until at least:
https://github.com/dart-lang/dartdoc/issues/766
is resolved, ideally also:
https://github.com/dart-lang/dartdoc/issues/763

@abarth
---
 sky/packages/sky/lib/mojo/activity.dart |  9 ++++++++-
 sky/packages/sky/lib/widgets.dart       |  2 ++
 sky/tools/skydoc.py                     | 18 +++++++++++++++---
 3 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/sky/packages/sky/lib/mojo/activity.dart b/sky/packages/sky/lib/mojo/activity.dart
index bfa5b66d31945..8be46a1e67b89 100644
--- a/sky/packages/sky/lib/mojo/activity.dart
+++ b/sky/packages/sky/lib/mojo/activity.dart
@@ -9,6 +9,11 @@ import 'package:sky_services/activity/activity.mojom.dart';
 
 export 'package:sky_services/activity/activity.mojom.dart' show Intent, ComponentName, StringExtra;
 
+/// Dart wrapper around Activity mojo service available in Sky on Android.
+///
+/// Most clients will want to use these methods instead of the activity service
+/// directly.
+
 const int NEW_DOCUMENT = 0x00080000;
 const int NEW_TASK = 0x10000000;
 const int MULTIPLE_TASK = 0x08000000;
@@ -24,15 +29,17 @@ final ActivityProxy _activity = _initActivity();
 Color _cachedPrimaryColor;
 String _cachedLabel;
 
-
+/// Ends the current activity.
 void finishCurrentActivity() {
   _activity.ptr.finishCurrentActivity();
 }
 
+/// Asks the Android ActivityManager to start a new Intent-based Activity.
 void startActivity(Intent intent) {
   _activity.ptr.startActivity(intent);
 }
 
+/// Sets the TaskDescription for the current Activity
 void updateTaskDescription(String label, Color color) {
   if (_cachedPrimaryColor == color && _cachedLabel == label)
     return;
diff --git a/sky/packages/sky/lib/widgets.dart b/sky/packages/sky/lib/widgets.dart
index fbd883613c533..02d619981f91f 100644
--- a/sky/packages/sky/lib/widgets.dart
+++ b/sky/packages/sky/lib/widgets.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+/// Includes and re-exports all Sky widgets classes.
+
 export 'widgets/animated_component.dart';
 export 'widgets/animated_container.dart';
 export 'widgets/basic.dart';
diff --git a/sky/tools/skydoc.py b/sky/tools/skydoc.py
index 05e7cf4f474d0..172e888c69d4e 100755
--- a/sky/tools/skydoc.py
+++ b/sky/tools/skydoc.py
@@ -7,17 +7,17 @@
 import os
 import subprocess
 import sys
+import webbrowser
+from skypy.url_mappings import URLMappings
 
 SKY_TOOLS_DIR = os.path.dirname(os.path.abspath(__file__))
 SKY_ROOT = os.path.dirname(SKY_TOOLS_DIR)
 SRC_ROOT = os.path.dirname(SKY_ROOT)
 WORKBENCH_ROOT = os.path.join(SRC_ROOT, 'sky', 'packages', 'workbench')
 
-from skypy.url_mappings import URLMappings
-
-
 DARTDOC = 'dartdoc'
 
+
 def main():
     try:
         subprocess.check_output([DARTDOC, '--version'])
@@ -27,20 +27,32 @@ def main():
 
     parser = argparse.ArgumentParser(description='Sky Documentation Generator')
     parser.add_argument('build_dir', type=str, help='Path to build output')
+    parser.add_argument('--open', action='store_true',
+         help='Open docs after building.')
     args = parser.parse_args()
 
     build_dir = os.path.abspath(args.build_dir)
 
     sky_package = os.path.join(SRC_ROOT, 'sky/packages/sky')
     doc_dir = os.path.join(build_dir, 'gen/dart-pkg/sky/doc')
+
+    # dartdoc doesn't understand sdk_ext yet, so we still need url_mappings:
+    # https://github.com/dart-lang/dartdoc/issues/763
     url_mappings = URLMappings(SRC_ROOT, build_dir)
 
     analyzer_args = [
         DARTDOC,
         '--input', sky_package,
         '--output', doc_dir,
+        # dartdoc appears to ignore --package-root:
+        # https://github.com/dart-lang/dartdoc/issues/766
+        '--package-root', os.path.join(WORKBENCH_ROOT, 'packages')
     ] + url_mappings.as_args
     subprocess.check_call(analyzer_args)
 
+    if args.open:
+        webbrowser.open(os.path.join(doc_dir, 'index.html'))
+
+
 if __name__ == '__main__':
     sys.exit(main())