Skip to content

Commit f2b68c0

Browse files
keertipkeertip
committed
Merge pull request #1154 from keertip/examples
add an option to inject examples
2 parents c08f180 + d592084 commit f2b68c0

File tree

6 files changed

+142
-94
lines changed

6 files changed

+142
-94
lines changed

‎bin/dartdoc.dart‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,6 @@ import 'package:dartdoc/src/package_meta.dart';
1414
import 'package:path/path.dart' as path;
1515
import 'package:stack_trace/stack_trace.dart';
1616

17-
bool _showProgress = false;
18-
1917
/// Analyzes Dart files and generates a representation of included libraries,
2018
/// classes, and members. Uses the current directory to look for libraries.
2119
main(List<String> arguments) async {
@@ -145,21 +143,7 @@ main(List<String> arguments) async {
145143
});
146144
}
147145

148-
void _onProgress(File file) {
149-
if (_showProgress) stdout.write('.');
150-
}
151-
152-
/// Print help if we are passed the help option.
153-
void _printHelp(ArgParser parser, {int exitCode: 0}) {
154-
print('Generate HTML documentation for Dart libraries.\n');
155-
_printUsageAndExit(parser, exitCode: exitCode);
156-
}
157-
158-
void _printUsageAndExit(ArgParser parser, {int exitCode: 0}) {
159-
print('Usage: dartdoc [OPTIONS]\n');
160-
print(parser.usage);
161-
exit(exitCode);
162-
}
146+
bool _showProgress = false;
163147

164148
ArgParser _createArgsParser() {
165149
var parser = new ArgParser();
@@ -214,6 +198,22 @@ ArgParser _createArgsParser() {
214198
return parser;
215199
}
216200

201+
void _onProgress(File file) {
202+
if (_showProgress) stdout.write('.');
203+
}
204+
205+
/// Print help if we are passed the help option.
206+
void _printHelp(ArgParser parser, {int exitCode: 0}) {
207+
print('Generate HTML documentation for Dart libraries.\n');
208+
_printUsageAndExit(parser, exitCode: exitCode);
209+
}
210+
211+
void _printUsageAndExit(ArgParser parser, {int exitCode: 0}) {
212+
print('Usage: dartdoc [OPTIONS]\n');
213+
print(parser.usage);
214+
exit(exitCode);
215+
}
216+
217217
String _resolveTildePath(String originalPath) {
218218
if (originalPath == null || !originalPath.startsWith('~/')) {
219219
return originalPath;

‎lib/dartdoc.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@ library dartdoc;
88
import 'dart:async';
99
import 'dart:io';
1010

11+
import 'package:analyzer/dart/element/element.dart';
1112
import 'package:analyzer/file_system/file_system.dart' as fileSystem;
1213
import 'package:analyzer/file_system/physical_file_system.dart';
1314
import 'package:analyzer/source/embedder.dart';
1415
import 'package:analyzer/source/package_map_provider.dart';
1516
import 'package:analyzer/source/package_map_resolver.dart';
1617
import 'package:analyzer/source/pub_package_map_provider.dart';
1718
import 'package:analyzer/source/sdk_ext.dart';
18-
import 'package:analyzer/dart/element/element.dart';
1919
import 'package:analyzer/src/generated/engine.dart';
2020
import 'package:analyzer/src/generated/error.dart';
2121
import 'package:analyzer/src/generated/java_io.dart';

‎lib/src/model.dart‎

Lines changed: 79 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -904,18 +904,8 @@ abstract class GetterSetterCombo {
904904
class Library extends ModelElement {
905905
static final Map<String, Library> _libraryMap = <String, Library>{};
906906

907-
static String getLibraryName(LibraryElement element) {
908-
String name = element.name;
909-
910-
if (name == null || name.isEmpty) {
911-
name = element.definingCompilationUnit.name;
912-
name = name.substring(0, name.length - '.dart'.length);
913-
}
914-
915-
return name;
916-
}
917-
918907
final Package package;
908+
919909
List<Class> _classes;
920910
List<Class> _enums;
921911
List<ModelFunction> _functions;
@@ -924,7 +914,6 @@ class Library extends ModelElement {
924914
Namespace _exportedNamespace;
925915
String _name;
926916
String _packageName;
927-
928917
factory Library(LibraryElement element, Package package) {
929918
String key = element == null ? 'null' : element.name;
930919

@@ -1023,21 +1012,6 @@ class Library extends ModelElement {
10231012
@override
10241013
String get href => '$dirName/$fileName';
10251014

1026-
String get packageName {
1027-
if (_packageName == null) {
1028-
String sourcePath = _library.source.fullName;
1029-
File file = new File(sourcePath);
1030-
if (file.existsSync()) {
1031-
_packageName = _getPackageName(file.parent);
1032-
if (_packageName == null) _packageName = '';
1033-
} else {
1034-
_packageName = '';
1035-
}
1036-
}
1037-
1038-
return _packageName;
1039-
}
1040-
10411015
bool get isAnonymous => element.name == null || element.name.isEmpty;
10421016

10431017
bool get isDocumented => oneLineDoc.isNotEmpty;
@@ -1073,6 +1047,21 @@ class Library extends ModelElement {
10731047
return _name;
10741048
}
10751049

1050+
String get packageName {
1051+
if (_packageName == null) {
1052+
String sourcePath = _library.source.fullName;
1053+
File file = new File(sourcePath);
1054+
if (file.existsSync()) {
1055+
_packageName = _getPackageName(file.parent);
1056+
if (_packageName == null) _packageName = '';
1057+
} else {
1058+
_packageName = '';
1059+
}
1060+
}
1061+
1062+
return _packageName;
1063+
}
1064+
10761065
String get path => _library.definingCompilationUnit.name;
10771066

10781067
/// All variables ("properties") except constants.
@@ -1162,6 +1151,17 @@ class Library extends ModelElement {
11621151
return _variables;
11631152
}
11641153

1154+
static String getLibraryName(LibraryElement element) {
1155+
String name = element.name;
1156+
1157+
if (name == null || name.isEmpty) {
1158+
name = element.definingCompilationUnit.name;
1159+
name = name.substring(0, name.length - '.dart'.length);
1160+
}
1161+
1162+
return name;
1163+
}
1164+
11651165
static String _getPackageName(Directory dir) {
11661166
if (!dir.existsSync() || !dir.path.contains(Platform.pathSeparator)) {
11671167
return null;
@@ -1343,6 +1343,7 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
13431343
}
13441344

13451345
_rawDocs = stripComments(_rawDocs) ?? '';
1346+
_rawDocs = _injectExamples(_rawDocs);
13461347
return _rawDocs;
13471348
}
13481349

@@ -1605,6 +1606,34 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
16051606

16061607
return '<a ${classContent}href="${href}">$name</a>';
16071608
}
1609+
1610+
// process the {@example ...} in comments and inject the example
1611+
// code into the doc commment.
1612+
// {@example core/ts/bootstrap/bootstrap.ts region='bootstrap'}
1613+
String _injectExamples(String rawdocs) {
1614+
if (rawdocs.contains('@example')) {
1615+
RegExp exp = new RegExp(r"{@example .+}");
1616+
Iterable<Match> matches = exp.allMatches(rawdocs);
1617+
var dirPath = this.package.packageMeta.dir.path;
1618+
for (var match in matches) {
1619+
var strings = match.group(0).split(' ');
1620+
var path = strings[1];
1621+
if (path.contains(Platform.pathSeparator) &&
1622+
!path.startsWith(Platform.pathSeparator)) {
1623+
var file = new File(p.join(dirPath, 'examples', path));
1624+
if (file.existsSync()) {
1625+
// TODO(keertip):inject example
1626+
} else {
1627+
var filepath =
1628+
this.element.source.fullName.substring(dirPath.length + 1);
1629+
stdout.write(
1630+
'\nwarning: ${filepath}: file ${strings[1]} does not exist.');
1631+
}
1632+
}
1633+
}
1634+
}
1635+
return rawdocs;
1636+
}
16081637
}
16091638

16101639
class ModelFunction extends ModelElement
@@ -1718,6 +1747,25 @@ class Package implements Nameable, Documentable {
17181747
_implementors.values.forEach((l) => l.sort());
17191748
}
17201749

1750+
List<PackageCategory> get categories {
1751+
Map<String, PackageCategory> result = {};
1752+
1753+
for (Library library in _libraries) {
1754+
String name = '';
1755+
1756+
if (library.name.startsWith('dart:')) {
1757+
name = 'Dart Core';
1758+
} else {
1759+
name = library.packageName;
1760+
}
1761+
1762+
if (!result.containsKey(name)) result[name] = new PackageCategory(name);
1763+
result[name]._libraries.add(library);
1764+
}
1765+
1766+
return result.values.toList()..sort();
1767+
}
1768+
17211769
String get documentation {
17221770
return hasDocumentationFile ? documentationFile.contents : null;
17231771
}
@@ -1732,43 +1780,24 @@ class Package implements Nameable, Documentable {
17321780

17331781
FileContents get documentationFile => packageMeta.getReadmeContents();
17341782

1783+
// TODO: make this work
17351784
bool get hasDocumentation =>
17361785
documentationFile != null && documentationFile.contents.isNotEmpty;
17371786

1738-
// TODO: make this work
1739-
bool get hasDocumentationFile => documentationFile != null;
1740-
17411787
// TODO: Clients should use [documentationFile] so they can act differently on
17421788
// plain text or markdown.
1789+
bool get hasDocumentationFile => documentationFile != null;
1790+
17431791
bool get hasMoreThanOneLineDocs => true;
17441792

1793+
// TODO: make this work
17451794
String get href => 'index.html';
17461795

1747-
// TODO: make this work
17481796
/// Does this package represent the SDK?
17491797
bool get isSdk => packageMeta.isSdk;
17501798

17511799
List<Library> get libraries => _libraries;
17521800

1753-
List<PackageCategory> get categories {
1754-
Map<String, PackageCategory> result = {};
1755-
1756-
for (Library library in _libraries) {
1757-
String name = '';
1758-
1759-
if (library.name.startsWith('dart:')) {
1760-
name = 'Dart Core';
1761-
} else {
1762-
name = library.packageName;
1763-
}
1764-
1765-
if (!result.containsKey(name)) result[name] = new PackageCategory(name);
1766-
result[name]._libraries.add(library);
1767-
}
1768-
1769-
return result.values.toList()..sort();
1770-
}
1771-
17721801
String get name => packageMeta.name;
17731802

17741803
String get oneLineDoc => '';

‎pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
name: dartdoc
22
# Also update the `version` field in lib/dartdoc.dart.
3-
version: 0.9.4
3+
version: 0.9.5-dev
44
author: Dart Team <misc@dartlang.org>
55
description: A documentation generator for Dart.
66
homepage: https://github.com/dart-lang/dartdoc

‎test/compare_output_test.dart‎

Lines changed: 43 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,16 @@ import 'dart:mirrors';
1111

1212
import 'package:path/path.dart' as p;
1313
import 'package:test/test.dart';
14-
1514
import 'package:which/which.dart';
1615

16+
const List<String> _filesToIgnore = const <String>['.DS_Store'];
17+
18+
const _gitBinName = 'git';
19+
20+
String _gitCache;
21+
22+
final _nameStatusLineRegexp = new RegExp(r'(\w)\t(.+)');
23+
1724
Uri get _currentFileUri =>
1825
(reflect(main) as ClosureMirror).function.location.sourceUri;
1926

@@ -27,6 +34,8 @@ void main() {
2734
group('compare outputs', () {
2835
Directory tempDir;
2936

37+
var dartdocBin = p.fromUri(_currentFileUri.resolve('../bin/dartdoc.dart'));
38+
3039
setUp(() {
3140
tempDir = Directory.systemTemp.createTempSync('dartdoc.test.');
3241
});
@@ -44,9 +53,6 @@ void main() {
4453
return;
4554
}
4655

47-
var dartdocBin =
48-
p.fromUri(_currentFileUri.resolve('../bin/dartdoc.dart'));
49-
5056
var args = <String>[
5157
dartdocBin,
5258
'--no-include-source',
@@ -99,12 +105,6 @@ void main() {
99105
];
100106
result = Process.runSync(gitPath, args);
101107
assert(result.exitCode != 0);
102-
// TODO(keertip): remove once 1.14 is stable; noSuchMethod documentation
103-
// has changed from 1.13 to 1.14.
104-
if (!result.stdout.contains('noSuchMethod')) {
105-
message.add("$v\t$k");
106-
message.add(result.stdout);
107-
}
108108
}
109109
});
110110

@@ -118,9 +118,42 @@ void main() {
118118

119119
fail(message.join('\n'));
120120
});
121+
122+
test('Check for sample code in examples', () {
123+
var args = <String>[
124+
dartdocBin,
125+
'--include',
126+
'ex',
127+
'--no-include-source',
128+
'--output',
129+
tempDir.path
130+
];
131+
132+
var result =
133+
Process.runSync('dart', args, workingDirectory: _testPackagePath);
134+
135+
if (result.exitCode != 0) {
136+
print(result.exitCode);
137+
print(result.stdout);
138+
print(result.stderr);
139+
fail('dartdoc failed');
140+
}
141+
142+
if (!result.stdout
143+
.contains('core/pipes/ts/slice_pipe/slice_pipe_example.ts')) {
144+
fail('Did not process @example in comments');
145+
}
146+
});
121147
}, onPlatform: {'windows': new Skip('Avoiding parsing git output')});
122148
}
123149

150+
Future<String> _gitBinPath() async {
151+
if (_gitCache == null) {
152+
_gitCache = await which(_gitBinName);
153+
}
154+
return _gitCache;
155+
}
156+
124157
Map<String, String> _parseOutput(
125158
String input, String sourcePath, String tempPath) {
126159
var values = <String, String>{};
@@ -149,18 +182,3 @@ Map<String, String> _parseOutput(
149182

150183
return values;
151184
}
152-
153-
const List<String> _filesToIgnore = const <String>['.DS_Store'];
154-
155-
final _nameStatusLineRegexp = new RegExp(r'(\w)\t(.+)');
156-
157-
const _gitBinName = 'git';
158-
159-
String _gitCache;
160-
161-
Future<String> _gitBinPath() async {
162-
if (_gitCache == null) {
163-
_gitCache = await which(_gitBinName);
164-
}
165-
return _gitCache;
166-
}

0 commit comments

Comments
 (0)