blob: 428f4c7fae623882541b37019c1c5bb310c8a6da [file] [log] [blame]
// Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
/// **docgen** is a tool for creating machine readable representations of Dart
/// code metadata, including: classes, members, comments and annotations.
/// docgen is run on a `.dart` file or a directory containing `.dart` files.
/// $ dart docgen.dart [OPTIONS] [FILE/DIR]
/// This creates files called `docs/<library_name>.yaml` in your current
/// working directory.
library docgen;
import 'dart:async';
import 'src/generator.dart' as gen;
import 'src/viewer.dart' as viewer;
export 'src/generator.dart' show getMirrorSystem;
export 'src/library_helpers.dart' show getDocgenObject;
export 'src/models.dart';
export 'src/package_helpers.dart' show packageNameFor;
/// Docgen constructor initializes the link resolver for markdown parsing.
/// Also initializes the command line arguments.
/// [packageRoot] is the packages directory of the directory being analyzed.
/// If [includeSdk] is `true`, then any SDK libraries explicitly imported will
/// also be documented.
/// If [parseSdk] is `true`, then all Dart SDK libraries will be documented.
/// This option is useful when only the SDK libraries are needed.
/// If [compile] is `true`, then after generating the documents, compile the
/// viewer with dart2js.
/// If [serve] is `true`, then after generating the documents we fire up a
/// simple server to view the documentation.
/// Returned Future completes with true if document generation is successful.
Future<bool> docgen(List<String> files, {String packageRoot,
bool includePrivate: false, bool includeSdk: false, bool parseSdk: false,
String introFileName: '', String out: gen.DEFAULT_OUTPUT_DIRECTORY,
List<String> excludeLibraries: const [],
bool includeDependentPackages: false, bool compile: false,
bool serve: false, bool noDocs: false, String startPage,
String pubScript : 'pub', String dartBinary: 'dart',
bool indentJSON: false}) {
var result;
if (!noDocs) {
result = gen.generateDocumentation(files, packageRoot: packageRoot,
includePrivate: includePrivate,
includeSdk: includeSdk, parseSdk: parseSdk,
introFileName: introFileName, out: out,
excludeLibraries: excludeLibraries,
includeDependentPackages: includeDependentPackages,
startPage: startPage, pubScriptValue: pubScript,
dartBinaryValue: dartBinary, indentJSON: indentJSON);
if (compile || serve) {
result.then((success) {
if (success) {
} else if (compile || serve) {
gen.pubScript = pubScript;
gen.dartBinary = dartBinary;
return result;