pkg/docgen/lib/docgen.dart

// 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 outputToYaml: false, bool includePrivate: false,
    bool includeSdk: false, bool parseSdk: false, bool append: 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,
    String dartBinary}) {
  var result;
  if (!noDocs) {
    viewer.ensureMovedViewerCode();
    result = gen.generateDocumentation(files, packageRoot: packageRoot,
        outputToYaml: outputToYaml, includePrivate: includePrivate,
        includeSdk: includeSdk, parseSdk: parseSdk, append: append,
        introFileName: introFileName, out: out,
        excludeLibraries: excludeLibraries,
        includeDependentPackages: includeDependentPackages,
        startPage: startPage, pubScript: pubScript, dartBinary: dartBinary);
    viewer.addBackViewerCode();
    if (compile || serve) {
      result.then((success) {
        if (success) {
          viewer.createViewer(serve);
        }
      });
    }
  } else if (compile || serve) {
    viewer.createViewer(serve);
  }
  return result;
}