Merge pull request #1154 from keertip/examples

add an option to inject examples

Author: keertip

bin/dartdoc.dart

@@ -14,8 +14,6 @@ import 'package:dartdoc/src/package_meta.dart';
 import 'package:path/path.dart' as path;
 import 'package:stack_trace/stack_trace.dart';
 
-bool _showProgress = false;
-
 /// Analyzes Dart files and generates a representation of included libraries,
 /// classes, and members. Uses the current directory to look for libraries.
 main(List<String> arguments) async {
@@ -145,21 +143,7 @@ main(List<String> arguments) async {
   });
 }
 
-void _onProgress(File file) {
-  if (_showProgress) stdout.write('.');
-}
-
-/// Print help if we are passed the help option.
-void _printHelp(ArgParser parser, {int exitCode: 0}) {
-  print('Generate HTML documentation for Dart libraries.\n');
-  _printUsageAndExit(parser, exitCode: exitCode);
-}
-
-void _printUsageAndExit(ArgParser parser, {int exitCode: 0}) {
-  print('Usage: dartdoc [OPTIONS]\n');
-  print(parser.usage);
-  exit(exitCode);
-}
+bool _showProgress = false;
 
 ArgParser _createArgsParser() {
   var parser = new ArgParser();
@@ -214,6 +198,22 @@ ArgParser _createArgsParser() {
   return parser;
 }
 
+void _onProgress(File file) {
+  if (_showProgress) stdout.write('.');
+}
+
+/// Print help if we are passed the help option.
+void _printHelp(ArgParser parser, {int exitCode: 0}) {
+  print('Generate HTML documentation for Dart libraries.\n');
+  _printUsageAndExit(parser, exitCode: exitCode);
+}
+
+void _printUsageAndExit(ArgParser parser, {int exitCode: 0}) {
+  print('Usage: dartdoc [OPTIONS]\n');
+  print(parser.usage);
+  exit(exitCode);
+}
+
 String _resolveTildePath(String originalPath) {
   if (originalPath == null || !originalPath.startsWith('~/')) {
     return originalPath;

lib/dartdoc.dart

@@ -8,14 +8,14 @@ library dartdoc;
 import 'dart:async';
 import 'dart:io';
 
+import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/file_system/file_system.dart' as fileSystem;
 import 'package:analyzer/file_system/physical_file_system.dart';
 import 'package:analyzer/source/embedder.dart';
 import 'package:analyzer/source/package_map_provider.dart';
 import 'package:analyzer/source/package_map_resolver.dart';
 import 'package:analyzer/source/pub_package_map_provider.dart';
 import 'package:analyzer/source/sdk_ext.dart';
-import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/src/generated/engine.dart';
 import 'package:analyzer/src/generated/error.dart';
 import 'package:analyzer/src/generated/java_io.dart';

lib/src/model.dart

@@ -904,18 +904,8 @@ abstract class GetterSetterCombo {
 class Library extends ModelElement {
   static final Map<String, Library> _libraryMap = <String, Library>{};
 
-  static String getLibraryName(LibraryElement element) {
-    String name = element.name;
-
-    if (name == null || name.isEmpty) {
-      name = element.definingCompilationUnit.name;
-      name = name.substring(0, name.length - '.dart'.length);
-    }
-
-    return name;
-  }
-
   final Package package;
+
   List<Class> _classes;
   List<Class> _enums;
   List<ModelFunction> _functions;
@@ -924,7 +914,6 @@ class Library extends ModelElement {
   Namespace _exportedNamespace;
   String _name;
   String _packageName;
-
   factory Library(LibraryElement element, Package package) {
     String key = element == null ? 'null' : element.name;
 
@@ -1023,21 +1012,6 @@ class Library extends ModelElement {
   @override
   String get href => '$dirName/$fileName';
 
-  String get packageName {
-    if (_packageName == null) {
-      String sourcePath = _library.source.fullName;
-      File file = new File(sourcePath);
-      if (file.existsSync()) {
-        _packageName = _getPackageName(file.parent);
-        if (_packageName == null) _packageName = '';
-      } else {
-        _packageName = '';
-      }
-    }
-
-    return _packageName;
-  }
-
   bool get isAnonymous => element.name == null || element.name.isEmpty;
 
   bool get isDocumented => oneLineDoc.isNotEmpty;
@@ -1073,6 +1047,21 @@ class Library extends ModelElement {
     return _name;
   }
 
+  String get packageName {
+    if (_packageName == null) {
+      String sourcePath = _library.source.fullName;
+      File file = new File(sourcePath);
+      if (file.existsSync()) {
+        _packageName = _getPackageName(file.parent);
+        if (_packageName == null) _packageName = '';
+      } else {
+        _packageName = '';
+      }
+    }
+
+    return _packageName;
+  }
+
   String get path => _library.definingCompilationUnit.name;
 
   /// All variables ("properties") except constants.
@@ -1162,6 +1151,17 @@ class Library extends ModelElement {
     return _variables;
   }
 
+  static String getLibraryName(LibraryElement element) {
+    String name = element.name;
+
+    if (name == null || name.isEmpty) {
+      name = element.definingCompilationUnit.name;
+      name = name.substring(0, name.length - '.dart'.length);
+    }
+
+    return name;
+  }
+
   static String _getPackageName(Directory dir) {
     if (!dir.existsSync() || !dir.path.contains(Platform.pathSeparator)) {
       return null;
@@ -1343,6 +1343,7 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
     }
 
     _rawDocs = stripComments(_rawDocs) ?? '';
+    _rawDocs = _injectExamples(_rawDocs);
     return _rawDocs;
   }
 
@@ -1605,6 +1606,34 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
 
     return '<a ${classContent}href="${href}">$name</a>';
   }
+
+  // process the {@example ...} in comments and inject the example
+  // code into the doc commment.
+  // {@example core/ts/bootstrap/bootstrap.ts region='bootstrap'}
+  String _injectExamples(String rawdocs) {
+    if (rawdocs.contains('@example')) {
+      RegExp exp = new RegExp(r"{@example .+}");
+      Iterable<Match> matches = exp.allMatches(rawdocs);
+      var dirPath = this.package.packageMeta.dir.path;
+      for (var match in matches) {
+        var strings = match.group(0).split(' ');
+        var path = strings[1];
+        if (path.contains(Platform.pathSeparator) &&
+            !path.startsWith(Platform.pathSeparator)) {
+          var file = new File(p.join(dirPath, 'examples', path));
+          if (file.existsSync()) {
+            // TODO(keertip):inject example
+          } else {
+            var filepath =
+                this.element.source.fullName.substring(dirPath.length + 1);
+            stdout.write(
+                '\nwarning: ${filepath}: file ${strings[1]} does not exist.');
+          }
+        }
+      }
+    }
+    return rawdocs;
+  }
 }
 
 class ModelFunction extends ModelElement
@@ -1718,6 +1747,25 @@ class Package implements Nameable, Documentable {
     _implementors.values.forEach((l) => l.sort());
   }
 
+  List<PackageCategory> get categories {
+    Map<String, PackageCategory> result = {};
+
+    for (Library library in _libraries) {
+      String name = '';
+
+      if (library.name.startsWith('dart:')) {
+        name = 'Dart Core';
+      } else {
+        name = library.packageName;
+      }
+
+      if (!result.containsKey(name)) result[name] = new PackageCategory(name);
+      result[name]._libraries.add(library);
+    }
+
+    return result.values.toList()..sort();
+  }
+
   String get documentation {
     return hasDocumentationFile ? documentationFile.contents : null;
   }
@@ -1732,43 +1780,24 @@ class Package implements Nameable, Documentable {
 
   FileContents get documentationFile => packageMeta.getReadmeContents();
 
+  // TODO: make this work
   bool get hasDocumentation =>
       documentationFile != null && documentationFile.contents.isNotEmpty;
 
-  // TODO: make this work
-  bool get hasDocumentationFile => documentationFile != null;
-
   // TODO: Clients should use [documentationFile] so they can act differently on
   // plain text or markdown.
+  bool get hasDocumentationFile => documentationFile != null;
+
   bool get hasMoreThanOneLineDocs => true;
 
+  // TODO: make this work
   String get href => 'index.html';
 
-  // TODO: make this work
   /// Does this package represent the SDK?
   bool get isSdk => packageMeta.isSdk;
 
   List<Library> get libraries => _libraries;
 
-  List<PackageCategory> get categories {
-    Map<String, PackageCategory> result = {};
-
-    for (Library library in _libraries) {
-      String name = '';
-
-      if (library.name.startsWith('dart:')) {
-        name = 'Dart Core';
-      } else {
-        name = library.packageName;
-      }
-
-      if (!result.containsKey(name)) result[name] = new PackageCategory(name);
-      result[name]._libraries.add(library);
-    }
-
-    return result.values.toList()..sort();
-  }
-
   String get name => packageMeta.name;
 
   String get oneLineDoc => '';

pubspec.yaml

@@ -1,6 +1,6 @@
 name: dartdoc
 # Also update the `version` field in lib/dartdoc.dart.
-version: 0.9.4
+version: 0.9.5-dev
 author: Dart Team <[email protected]>
 description: A documentation generator for Dart.
 homepage: https://github.com/dart-lang/dartdoc

test/compare_output_test.dart

@@ -11,9 +11,16 @@ import 'dart:mirrors';
 
 import 'package:path/path.dart' as p;
 import 'package:test/test.dart';
-
 import 'package:which/which.dart';
 
+const List<String> _filesToIgnore = const <String>['.DS_Store'];
+
+const _gitBinName = 'git';
+
+String _gitCache;
+
+final _nameStatusLineRegexp = new RegExp(r'(\w)\t(.+)');
+
 Uri get _currentFileUri =>
     (reflect(main) as ClosureMirror).function.location.sourceUri;
 
@@ -27,6 +34,8 @@ void main() {
   group('compare outputs', () {
     Directory tempDir;
 
+    var dartdocBin = p.fromUri(_currentFileUri.resolve('../bin/dartdoc.dart'));
+
     setUp(() {
       tempDir = Directory.systemTemp.createTempSync('dartdoc.test.');
     });
@@ -44,9 +53,6 @@ void main() {
         return;
       }
 
-      var dartdocBin =
-          p.fromUri(_currentFileUri.resolve('../bin/dartdoc.dart'));
-
       var args = <String>[
         dartdocBin,
         '--no-include-source',
@@ -99,12 +105,6 @@ void main() {
           ];
           result = Process.runSync(gitPath, args);
           assert(result.exitCode != 0);
-          // TODO(keertip): remove once 1.14 is stable; noSuchMethod documentation
-          // has changed from 1.13 to 1.14.
-          if (!result.stdout.contains('noSuchMethod')) {
-            message.add("$v\t$k");
-            message.add(result.stdout);
-          }
         }
       });
 
@@ -118,9 +118,42 @@ void main() {
 
       fail(message.join('\n'));
     });
+
+    test('Check for sample code in examples', () {
+      var args = <String>[
+        dartdocBin,
+        '--include',
+        'ex',
+        '--no-include-source',
+        '--output',
+        tempDir.path
+      ];
+
+      var result =
+          Process.runSync('dart', args, workingDirectory: _testPackagePath);
+
+      if (result.exitCode != 0) {
+        print(result.exitCode);
+        print(result.stdout);
+        print(result.stderr);
+        fail('dartdoc failed');
+      }
+
+      if (!result.stdout
+          .contains('core/pipes/ts/slice_pipe/slice_pipe_example.ts')) {
+        fail('Did not process @example in comments');
+      }
+    });
   }, onPlatform: {'windows': new Skip('Avoiding parsing git output')});
 }
 
+Future<String> _gitBinPath() async {
+  if (_gitCache == null) {
+    _gitCache = await which(_gitBinName);
+  }
+  return _gitCache;
+}
+
 Map<String, String> _parseOutput(
     String input, String sourcePath, String tempPath) {
   var values = <String, String>{};
@@ -149,18 +182,3 @@ Map<String, String> _parseOutput(
 
   return values;
 }
-
-const List<String> _filesToIgnore = const <String>['.DS_Store'];
-
-final _nameStatusLineRegexp = new RegExp(r'(\w)\t(.+)');
-
-const _gitBinName = 'git';
-
-String _gitCache;
-
-Future<String> _gitBinPath() async {
-  if (_gitCache == null) {
-    _gitCache = await which(_gitBinName);
-  }
-  return _gitCache;
-}