dartdoc Library / Dart API Reference

dartdoc library

To generate docs for a library, run this script with the path to an entrypoint .dart file, like:

$ dart dartdoc.dart foo.dart

This will create a "docs" directory with the docs for your libraries. To create these beautiful docs, dartdoc parses your library and every library it imports (recursively). From each library, it parses all classes and members, finds the associated doc comments and builds crosslinked docs from them.

Properties

const API_LOCATION #

const API_LOCATION = 'http://api.dartlang.org/';

const String ARGS #

const String ARGS = 'args';

const String CLASS #

const String CLASS = 'class';

const String CONSTRUCTOR #

const String CONSTRUCTOR = 'constructor';

const String FIELD #

const String FIELD = 'field';

const String GETTER #

const String GETTER = 'getter';

const String INTERFACE #

const String INTERFACE = 'interface';

const String KIND #

const String KIND = 'kind';

const String LIBRARY #

const String LIBRARY = 'library';

const String LINK_NAME #

const String LINK_NAME = 'link_name';

const String MEMBERS #

const String MEMBERS = 'members';

const String METHOD #

const String METHOD = 'method';

const MODE_LIVE_NAV #

Generated docs do not include baked HTML navigation. Instead, a single nav.json file is created and the appropriate navigation is generated client-side by parsing that and building HTML.

This dramatically reduces the generated size of the HTML since a large fraction of each static page is just redundant navigation links.

In this mode, the browser will do a XHR for nav.json which means that to preview docs locally, you will need to enable requesting file:// links in your browser or run a little local server like python -m SimpleHTTPServer.

const MODE_LIVE_NAV = 1;

const MODE_STATIC #

Generates completely static HTML containing everything you need to browse the docs. The only client side behavior is trivial stuff like syntax highlighting code.

const MODE_STATIC = 0;

const String NAME #

const String NAME = 'name';

const String NO_PARAMS #

const String NO_PARAMS = 'noparams';

final Path scriptDir #

Gets the full path to the directory containing the entrypoint of the current script. In other words, if you invoked dartdoc, directly, it will be the path to the directory containing dartdoc.dart. If you're running a script that imports dartdoc, it will be the path to that script.

Path get scriptDir =>
    new Path.fromNative(new Options().script).directoryPath;

const String SETTER #

const String SETTER = 'setter';

const String TYPEDEF #

const String TYPEDEF = 'typedef';

const String TYPES #

const String TYPES = 'types';

Functions

void writeString(File file, String text) #

void writeString(File file, String text) {
  var randomAccessFile = file.openSync(FileMode.WRITE);
  randomAccessFile.writeStringSync(text);
  randomAccessFile.closeSync();
}

String joinWithCommas(List<String> items, [String conjunction = 'and']) #

Joins items into a single, comma-separated string using conjunction. E.g. ['A', 'B', 'C'] becomes "A, B, and C".

String joinWithCommas(List<String> items, [String conjunction = 'and']) {
  if (items.length == 1) return items[0];
  if (items.length == 2) return "${items[0]} $conjunction ${items[1]}";
  return '${Strings.join(items.getRange(0, items.length - 1), ', ')}'
    ', $conjunction ${items[items.length - 1]}';
}

List<Mirror> orderByName(Collection<Mirror> list) #

Sorts the map by the key, doing a case-insensitive comparison.

List<Mirror> orderByName(Collection<Mirror> list) {
  final elements = new List<Mirror>.from(list);
  elements.sort((a,b) {
    String aName = a.simpleName.toLowerCase();
    String bName = b.simpleName.toLowerCase();
    bool doma = aName.startsWith(r"$dom");
    bool domb = bName.startsWith(r"$dom");
    return doma == domb ? aName.compareTo(bName) : doma ? 1 : -1;
  });
  return elements;
}

String unindent(String text, int indentation) #

Removes up to indentation leading whitespace characters from text.

String unindent(String text, int indentation) {
  var start;
  for (start = 0; start < min(indentation, text.length); start++) {
    // Stop if we hit a non-whitespace character.
    if (text[start] != ' ') break;
  }

  return text.substring(start);
}

String repeat(String text, int count, [String separator]) #

Repeats [text] [count] times, separated by separator if given.

String repeat(String text, int count, {String separator}) {
  // TODO(rnystrom): Should be in corelib.
  final buffer = new StringBuffer();
  for (int i = 0; i < count; i++) {
    buffer.add(text);
    if ((i < count - 1) && (separator !== null)) buffer.add(separator);
  }

  return buffer.toString();
}

int countOccurrences(String text, String search) #

Returns the number of times search occurs in text.

int countOccurrences(String text, String search) {
  int start = 0;
  int count = 0;

  while (true) {
    start = text.indexOf(search, start);
    if (start == -1) break;
    count++;
    // Offsetting by search length means overlapping results are not counted.
    start += search.length;
  }

  return count;
}

String sanitize(String name) #

Turns name into something that's safe to use as a file name.

String sanitize(String name) => name.replaceAll(':', '_').replaceAll('/', '_');

String kindToString(String kind) #

Translation of const values to strings. Used to facilitate shortening of constant value strings.

String kindToString(String kind) {
  if (kind == LIBRARY) {
    return 'library';
  } else if (kind == CLASS) {
    return 'class';
  } else if (kind == INTERFACE) {
    return 'interface';
  } else if (kind == TYPEDEF) {
    return 'typedef';
  } else if (kind == FIELD) {
    return 'field';
  } else if (kind == CONSTRUCTOR) {
    return 'constructor';
  } else if (kind == METHOD) {
    return 'method';
  } else if (kind == GETTER) {
    return 'getter';
  } else if (kind == SETTER) {
    return 'setter';
  }
  return '';
}

Future<bool> compileScript(int mode, Path outputDir, Path libPath) #

Compiles the dartdoc client-side code to JavaScript using Dart2js.

Future<bool> compileScript(int mode, Path outputDir, Path libPath) {
  var clientScript = (mode == MODE_STATIC) ? 'static' : 'live-nav';
  var dartPath = libPath.append(
      'pkg/dartdoc/lib/src/client/client-$clientScript.dart');
  var jsPath = outputDir.append('client-$clientScript.js');

  var completer = new Completer<bool>();
  var compilation = new Compilation(dartPath, libPath);
  Future<String> result = compilation.compileToJavaScript();
  result.then((jsCode) {
    writeString(new File.fromPath(jsPath), jsCode);
    completer.complete(true);
  });
  result.handleException((e) => completer.completeException(e));
  return completer.future;
}

Future copyDirectory(Path from, Path to) #

Copies all of the files in the directory from to to. Does not recursively copy subdirectories.

Note: runs asynchronously, so you won't see any files copied until after the event loop has had a chance to pump (i.e. after main() has returned).

Future copyDirectory(Path from, Path to) {
  final completer = new Completer();
  final fromDir = new Directory.fromPath(from);
  final lister = fromDir.list(recursive: false);

  lister.onFile = (String path) {
    final name = new Path.fromNative(path).filename;
    // TODO(rnystrom): Hackish. Ignore 'hidden' files like .DS_Store.
    if (name.startsWith('.')) return;

    File fromFile = new File(path);
    File toFile = new File.fromPath(to.append(name));
    fromFile.openInputStream().pipe(toFile.openOutputStream());
  };
  lister.onDone = (done) => completer.complete(true);
  return completer.future;
}

void cleanOutputDirectory(Path path) #

Deletes and recreates the output directory at path if it exists.

void cleanOutputDirectory(Path path) {
  final outputDir = new Directory.fromPath(path);
  if (outputDir.existsSync()) {
    outputDir.deleteRecursivelySync();
  }

  try {
    // TODO(3914): Hack to avoid 'file already exists' exception thrown
    // due to invalid result from dir.existsSync() (probably due to race
    // conditions).
    outputDir.createSync();
  } on DirectoryIOException catch (e) {
    // Ignore.
  }
}

dartdoc

dartdoc library

Properties

Code const API_LOCATION #

Code const String ARGS #

Code const String CLASS #

Code const String CONSTRUCTOR #

Code const String FIELD #

Code const String GETTER #

Code const String INTERFACE #

Code const String KIND #

Code const String LIBRARY #

Code const String LINK_NAME #

Code const String MEMBERS #

Code const String METHOD #

Code const MODE_LIVE_NAV #

Code const MODE_STATIC #

Code const String NAME #

Code const String NO_PARAMS #

Code final Path scriptDir #

Code const String SETTER #

Code const String TYPEDEF #

Code const String TYPES #