Skip to content

Improve package description and add brief example reference #2079

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Nov 22, 2019
Merged

Improve package description and add brief example reference #2079

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e104540
Improve package description and add brief example reference
jcollins-g Nov 21, 2019
aa63f39
Move pub to end and put a warning on it
jcollins-g Nov 21, 2019
4660365
Fix test
jcollins-g Nov 22, 2019
99a5a2f
dartfmt
jcollins-g Nov 22, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions example/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# 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`.

## 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.

## 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.
2 changes: 1 addition & 1 deletion pubspec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: dartdoc
# Run `grind build` after updating.
version: 0.29.1
author: Dart Team <[email protected]>
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'
Expand Down
5 changes: 4 additions & 1 deletion test/package_meta_test.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,10 @@ 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', () {
Expand Down