From e1045405cc3039623cf63946d35c5476d4c02a81 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Thu, 21 Nov 2019 09:14:37 -0800 Subject: [PATCH 1/4] Improve package description and add brief example reference --- example/README.md | 28 ++++++++++++++++++++++++++++ pubspec.yaml | 2 +- 2 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 example/README.md diff --git a/example/README.md b/example/README.md new file mode 100644 index 0000000000..d397fc73e8 --- /dev/null +++ b/example/README.md @@ -0,0 +1,28 @@ +# dartdoc examples + +Dartdoc is typically used as a command line utility to support generating +documentation served on websites. In the future this directory may contain +direct examples, but for now, here are pointers to the main users of dartdoc +in the Dart ecosystem. + +## Dart SDK + +The Dart team builds docs for the [Dart API reference](https://api.dart.dev/) +with each new version of the SDK, via +[this script](https://github.com/dart-lang/sdk/blob/master/tools/bots/dart_sdk.py). +Look for `BuildDartdocAPIDocs`. + +## pub + +The [pub package website](https://pub.dev) automatically builds Dart +[API documentation](https://pub.dev/documentation/dartdoc/latest/) +for [uploaded packages](https://pub.dev/packages/dartdoc). Unlike the other two +examples, dartdoc is used as a library. See [this script](https://github.com/dart-lang/pub-dev/blob/master/pkg/pub_dartdoc/bin/pub_dartdoc.dart) +for the entry point. + +## Flutter + +The Flutter team builds [API documentation for the Flutter SDK](https://api.flutter.dev) +automatically. A [shell script](https://github.com/flutter/flutter/blob/master/dev/bots/docs.sh) +wraps a [small dart program](https://github.com/flutter/flutter/blob/master/dev/tools/dartdoc.dart) +that manages the process. \ No newline at end of file diff --git a/pubspec.yaml b/pubspec.yaml index 4d24979772..bf037d19a5 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -2,7 +2,7 @@ name: dartdoc # Run `grind build` after updating. version: 0.29.1 author: Dart Team -description: A documentation generator for Dart. +description: A non-interactive HTML documentation generator for Dart source code. homepage: https://github.com/dart-lang/dartdoc environment: sdk: '>=2.6.0 <3.0.0' From aa63f39a0be4f24db7b1302fdd4e1a7ed0a3c011 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Thu, 21 Nov 2019 09:31:30 -0800 Subject: [PATCH 2/4] Move pub to end and put a warning on it --- example/README.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/example/README.md b/example/README.md index d397fc73e8..c6d814e8eb 100644 --- a/example/README.md +++ b/example/README.md @@ -12,17 +12,22 @@ with each new version of the SDK, via [this script](https://github.com/dart-lang/sdk/blob/master/tools/bots/dart_sdk.py). Look for `BuildDartdocAPIDocs`. -## pub - -The [pub package website](https://pub.dev) automatically builds Dart -[API documentation](https://pub.dev/documentation/dartdoc/latest/) -for [uploaded packages](https://pub.dev/packages/dartdoc). Unlike the other two -examples, dartdoc is used as a library. See [this script](https://github.com/dart-lang/pub-dev/blob/master/pkg/pub_dartdoc/bin/pub_dartdoc.dart) -for the entry point. - ## Flutter The Flutter team builds [API documentation for the Flutter SDK](https://api.flutter.dev) automatically. A [shell script](https://github.com/flutter/flutter/blob/master/dev/bots/docs.sh) wraps a [small dart program](https://github.com/flutter/flutter/blob/master/dev/tools/dartdoc.dart) -that manages the process. \ No newline at end of file +that manages the process. + +## pub + +The [pub package website](https://pub.dev) automatically builds Dart +[API documentation](https://pub.dev/documentation/dartdoc/latest/) +for [uploaded packages](https://pub.dev/packages/dartdoc). + +Note, unlike the other two examples, here dartdoc is used as a library. While we make some +effort not to regularly break simple uses of the library interface, we strongly recommend +you use the command line and focus our semantic versioning around that case. However, if +that doesn't work for your case, the pub site usage may be of interest. See +[this script](https://github.com/dart-lang/pub-dev/blob/master/pkg/pub_dartdoc/bin/pub_dartdoc.dart) +for the entry point. \ No newline at end of file From 4660365862a0db97c2e6ca9227fe220340186a2f Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Fri, 22 Nov 2019 09:19:43 -0800 Subject: [PATCH 3/4] Fix test --- test/package_meta_test.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/package_meta_test.dart b/test/package_meta_test.dart index dd231b65d7..e4c78b688c 100644 --- a/test/package_meta_test.dart +++ b/test/package_meta_test.dart @@ -46,7 +46,7 @@ void main() { }); test('has a description', () { - expect(p.description, equals('A documentation generator for Dart.')); + expect(p.description, equals('A non-interactive HTML documentation generator for Dart source code.')); }); test('has a homepage', () { From 99a5a2f8d2142037cd29837da20316096a013538 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Fri, 22 Nov 2019 09:55:47 -0800 Subject: [PATCH 4/4] dartfmt --- test/package_meta_test.dart | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/test/package_meta_test.dart b/test/package_meta_test.dart index e4c78b688c..678dd0ee9d 100644 --- a/test/package_meta_test.dart +++ b/test/package_meta_test.dart @@ -46,7 +46,10 @@ void main() { }); test('has a description', () { - expect(p.description, equals('A non-interactive HTML documentation generator for Dart source code.')); + expect( + p.description, + equals( + 'A non-interactive HTML documentation generator for Dart source code.')); }); test('has a homepage', () {