Merge pull request #457 from eseidelGoogle/docs

Add a few bits of documentation to package:sky

Author: eseidelGoogle

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;

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';

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())