From 276bad6919be6a8de39fc33f02a523911da72f16 Mon Sep 17 00:00:00 2001
From: rolux <rolux@rolux.org>
Date: Sun, 24 Jun 2012 17:14:56 +0200
Subject: [PATCH] update oxdoc article

---
 readme/{documentation.html => oxdoc.html} | 25 +++++++++++++----------
 1 file changed, 14 insertions(+), 11 deletions(-)
 rename readme/{documentation.html => oxdoc.html} (53%)

diff --git a/readme/documentation.html b/readme/oxdoc.html
similarity index 53%
rename from readme/documentation.html
rename to readme/oxdoc.html
index 6ea41c83..df9681c9 100644
--- a/readme/documentation.html
+++ b/readme/oxdoc.html
@@ -1,31 +1,34 @@
-<h1>OxDoc - A JavaScript Documentation Language</h1>
+<h1>OxDoc — A JavaScript Documentation Language</h1>
 
-<p>Nothing to see here yet, please move along...</p>
+<p><code>OxDoc</code> is a new format for JavaScript documentation. It was developed for and is used throughout <code>OxJS</code>, which provides a <a href="#doc/Ox.doc">parser</a> and a <a href="#doc/Ox.DocPanel">browser</a> for it.</p>
 
-<pre class="code" id="doc">
+<p><code>OxDoc</code> itself isn't formally documented yet, but you may want to take a look at the extensive <a href="#examples/oxdoc_tutorial">tutorial</a>. The sample below should give you a rough first idea.</p>
+
+<p>For now, <code>OxDoc</code> should be considered a proposal, and this introduction is, above all, a request for <a href="#development">comments</a>.</p>
+
+<pre class="code">
 //@ Section Name
-My = {};
+this.My = {};
 //@ My.foo &lt;number> One-line summary, with *some* `markdown`
 My.foo = 23;
 /*@
 My.bar &lt;object> Summary
     Optional multi-line description, with *some* `markdown`.
-    property &lt;object> A property of My.bar
-        Description
+    property &lt;object> A property of `My.bar`
+        Description of `property`.
         foo &lt;number> A number
         bar &lt;[string]> An array of strings
-    method &lt;function> A method of My.bar
+    method &lt;function> A method of `My.bar`
         (foo[, bar], callback) -> &lt;undefined> Return value
         foo &lt;number|string> Argument, number or string
         bar &lt;boolean|false> Optional argument, default is `false`
         callback &lt;function> Callback function
             arg &lt;boolean> Argument
-    baz &lt;event> An event triggered by My.bar
+    baz &lt;event> An event triggered by `My.bar`
         x &lt;number> Event property
         y &lt;number> Event property
-    # This is a comment. Below are inline tests (the first one will fail, the
-    # last one is asynchronous).
-    > My.bar.property.foo > 1
+    # This is a comment. Below are inline tests. The last one is asynchronous.
+    > My.bar.property.foo &lt; 1
     true
     > My.bar.property.bar.join('')
     'string'