Lots of stuff hooking up markdown to dartdoc.

utils/dartdoc/README.txt

Index: utils/dartdoc/README.txt
diff --git a/utils/dartdoc/README.txt b/utils/dartdoc/README.txt
index f76aa70af5c0a5e82d113afb415fc52e05645158..01eb65269174dc4b0b45cf0268c32a9a714aae4c 100644
--- a/utils/dartdoc/README.txt
+++ b/utils/dartdoc/README.txt
@@ -1,14 +1,72 @@
-TODO(rnystrom): This is moving from a sample to being a real project. Right
-now, to try this out:
+Dartdoc generates static HTML documentation from Dart code.
 
-1. Compile interact.dart to JS:
-   dartdoc$ ../../frog/frogsh --libdir=../../frog/lib --out=docs/interact.js \
-     --compile-only interact.dart
+To use it, from this directory, run:

[nweiz, 2011/11/28 22:50:45]

What would it take for this to be runnable from an arbitrary directory?

[Bob Nystrom, 2011/11/29 02:44:08]

Some shell shenanigans. It's a little tricky even running frog from other
directories, but I can look into it at some point.

 
-2. Run the doc generator:
-   dartdoc$ ../../frog/frogsh --libdir=../../frog/lib dartdoc.dart dartdoc.dart
+    $ dartdoc <path to .dart file>
 
-   Note here that the first "dartdoc.dart" is to run this program, and the
-   second is passing its own name to itself to generate its own docs.
+This will create a "docs" directory with the docs for your libraries. To do so,
+dartdoc parses that library and every library it imports. From each library, it
+parses all classes and members, finds the associated doc comments and builds
+crosslinked docs from them.
 
-3. Look at the results in frog/docs/
+"Doc comments" can be in one of a few forms:
+
+    /**
+     * JavaDoc style block comments.
+     */
+
+    /** Which can also be single line. */
+
+    /// Triple-slash line comments.
+    /// Which can be multiple lines.
+
+The body of a doc comment will be parsed as markdown which means you can apply
+most of the formatting and structuring you want while still having docs that
+look nice in plain text. For example:
+
+    /// This is a doc comment. This is the first paragraph in the comment. It
+    /// can span multiple lines.
+    ///
+    /// A blank line starts a new paragraph like this one.
+    ///
+    /// *   Unordered lists start with `*` or `-` or `+`.
+    /// *   And can have multiple items.
+    ///     1. You can nest lists.
+    ///     2. Like this numbered one.
+    ///
+    /// ---
+    ///
+    /// Three dashes, underscores, or tildes on a line by themselves create a
+    /// horizontal rule.
+    ///
+    ///     to.get(a.block + of.code) {
+    ///       indent(it, 4.lines);
+    ///       like(this);
+    ///     }
+    ///
+    /// There are a few inline styles you can apply: *emphasis*, **strong**,
+    /// and `inline code`. You can also use underscores for _emphasis_ and
+    /// __strong__.
+    ///
+    /// An H1 header using equals on the next line
+    /// ==========================================
+    ///
+    /// And an H2 in that style using hyphens
+    /// -------------------------------------
+    ///
+    /// # Or an H1 - H6 using leading hashes
+    /// ## H2
+    /// ### H3
+    /// #### H4 you can also have hashes at then end: ###
+    /// ##### H5
+    /// ###### H6
+
+There is also an extension to markdown specific to dartdoc: A name inside
+square brackets that is not a markdown link (i.e. doesn't have square brackets
+or parentheses following it) like:
+
+    Calls [someMethod], passing in [arg].
+
+is understood to be the name of some member or type that's in the scope of the
+member where that comment appears. Dartdoc will automatically figure out what
+the name refers to and generate an approriate link to that member or type.