How to Edit API Docs - kwalrath/bleeding_edge GitHub Wiki

This page describes how to generate the API docs by hand, so that you can test your doc comments before submitting changes.

Once you submit your doc comments and they're merged into the main Dart repository, the generated docs should be automatically uploaded within 1 day. {PENDING: can we be more precise?}

The whole process, start to finish

1. Get the Dart source code. Follow the instructions in Getting the Source. {PENDING: Do you really need the whole thing? It'd be nice if the github project were a subset of the regular project (plus a custom README).}

2. Edit the doc comments, following the doc comment guidelines.

   • To change the HTML doc comments, refer to Contributing HTML Documentation.
   • To change other doc comments, edit sdk/lib/LIB_NAME/FILE.dart.

3. Remove the old doc build, if it exists:

rm -r xcodebuild/ReleaseIA32/api_docs/*

4. Do a build. For non-HTML docs, it's something like this:

./tools/build.py -m release

(Is a whole build really necessary? It'd be nice if you could check your changes online.)

5. Using a file: URL, view the docs. E.g.:

file:///Users/me/dart-all/dart/xcodebuild/ReleaseIA32/api_docs/index.html

Repeat steps 2-4 as necessary.

Once you've confirmed that everything's OK, get your changes reviewed and submit them, using the usual process.
It should be something like this (for now):

git cl upload ...Get approval... git cl push

## Finding the right file to edit
* To edit top-level member and library descriptions, search for "library". For example:

cd sdk/lib/io grep -l library *.dart vim io.dart