use markdown

examples/manhattan_grid/js/example.js

@@ -1,8 +1,9 @@
 /*
-The idea (a slight variation of a proposal by
+The idea (a slight variation of a proposal by [Harold
-<a href="http://extendny.com/">Harold Cooper</a>) is to extend the Manhattan
+Cooper](http://extendny.com/)) is to extend the Manhattan Grid in all
-Grid in all directions, so that every point on Earth can be addressed as
+directions, so that every point on Earth can be addressed as "Xth Ave & Yth
-"Xth Ave & Yth St".<br><br>
+St".
+
 The origin of this coordinate system is the intersection of Zero Ave (a.k.a.
 Avenue A) and Zero St (a.k.a. Houston St). Avenues east of Zero Ave, just as
 Streets south of Zero St, have negative numbers. Broadway, which will split not
@@ -11,7 +12,8 @@ retains its orientation, but is adjusted slightly so that it originates at the
 intersection of Zero & Zero. From there, Broadway, Zero Avenue and Zero Street
 continue as perfectly straight equatorial lines. All three will intersect once
 more, exactly halfway, in the Indian Ocean, (southwest of Australia), at the
-point furthest from Manhattan.<br><br>
+point furthest from Manhattan.
+
 As subsequent avenues remain exactly parallel to Zero Ave, and subsequent
 streets exactly parallel to Zero St, they form smaller and smaller circles
 around the globe. The northernmost and southernmost streets are small circles
@@ -144,7 +146,7 @@ Ox.load('Image', function() {
         east: Ox.getPoint(points['0 & 0'], -C / 4, bearings.streets),
         /*
         Broadway has two poles as well, and constructing them will make drawing
-        easier. Ox.mod is the modulo function. Unlike <code>-90 % 360</code>,
+        easier. Ox.mod is the modulo function. Unlike `-90 % 360`,
         which in JavaScript is -90, Ox.mod(-90, 360) returns 270.
         */
         westBroadway: Ox.getPoint(
@@ -162,7 +164,7 @@ Ox.load('Image', function() {
     Now we calculate circles for Broadway, Avenues and Streets. Ox.getCircle
     returns an array of lat/lng pairs that form a circle around a given point,
     with a given radius and a given precision, so that the circle will have
-    <code>Math.pow(2, precision)</code> segments. 
+    `Math.pow(2, precision)` segments. 
     */
     lines = {
         /*
@@ -209,10 +211,10 @@ Ox.load('Image', function() {
 
     /*
     Before we start drawing, we define a few helper functions.
-    <code>getXYByLatLng</code> returns screen coordinates for a given point.
+    `getXYByLatLng` returns screen coordinates for a given point.
     We use Ox.getXYByLatLng, which takes a lat/lng pair and returns its x/y
-    position on a 1×1 Mercator position, with <code>{x: 0, y: 0}</code> at the
+    position on a 1×1 Mercator position, with `{x: 0, y: 0}` at the
-    bottom left and <code>{x: 1, y: 1}</code> at the top right.
+    bottom left and `{x: 1, y: 1}` at the top right.
     */
     function getXYByLatLng(point) {
         return Ox.map(Ox.getXYByLatLng(point), function(v) {
@@ -221,7 +223,7 @@ Ox.load('Image', function() {
     }
 
     /*
-    <code>getLatLngByXY</code> is the inverse of the above, just like
+    `getLatLngByXY` is the inverse of the above, just like
     Ox.getLatLngByXY.
     */
     function getLatLngByXY(xy) {
@@ -231,7 +233,7 @@ Ox.load('Image', function() {
     }
 
     /*
-    <code>getASByLatLng</code> takes lat/lng and returns avenue/street. To
+    `getASByLatLng` takes lat/lng and returns avenue/street. To
     compute the avenue, we subtract the point's distance from the West Pole, in
     avenues, from the total number of avenues. To compute the street, we
     subtract the point's distance from the North Pole, in avenues, from the
@@ -260,7 +262,7 @@ Ox.load('Image', function() {
     }
 
     /*
-    <code>getASByXY</code> returns avenue and street at the given screen
+    `getASByXY` returns avenue and street at the given screen
     coordinates.
     */
     function getASByXY(xy) {
@@ -268,7 +270,7 @@ Ox.load('Image', function() {
     }
 
     /*
-    <code>drawPath</code> draws a path of lat/lng pairs on an image. For each
+    `drawPath` draws a path of lat/lng pairs on an image. For each
     path segment, we have to check if it crosses the eastern or western edge of
     the map that splits the Pacific Ocean. Note that our test (a segment
     crosses the edge if it spans more than 180 degrees longitude) is obviously

source/Ox.UI/js/Code/SourceViewer.js

@@ -42,10 +42,13 @@ Ox.SourceViewer = function(options, self) {
         var sections = [{comment: '', code: ''}];
         Ox.tokenize(source).forEach(function(token, i) {
             var type = token.type == 'comment' ? 'comment' : 'code';
+            // ignore '//' comments
             if (!/^\/\//.test(token.value)) {
                 if (type == 'comment') {
                     i && sections.push({comment: '', code: ''});
-                    token.value = expand(trim(token.value.slice(2, -2)));
+                    token.value = Ox.parseMarkdown(
+                        trim(token.value.slice(2, -2))
+                    );
                     self.options.replaceComment.forEach(function(replace) {
                         token.value = token.value.replace(
                             replace[0], replace[1]
@@ -77,7 +80,7 @@ Ox.SourceViewer = function(options, self) {
     function expand(str) {
         return str.replace(/(\W)`([\s\S]+?)`/g, function(match, outer, inner) {
             return outer + '<code>' + Ox.encodeHTMLEntities(inner) + '</code>';
-        })
+        });
     }
 
     function trim(str) {

source/Ox/js/Array.js

@@ -2,15 +2,15 @@
 
 /*@
 Ox.api <f> Turns an array into a list API
-    <code>Ox.api</code> takes an array and returns a function that allows you to
+    `Ox.api` takes an array and returns a function that allows you to run
-    run complex queries against it. See the examples below for details.
+    complex queries against it. See the examples below for details.
     (items, options) -> <f> List API
     items <[o]> An array of objects (key/value stores)
     options <o> Options object
         cache <b|false> If true, cache results
-        enums <o> Enumerables, for example <code>{size: ['S', 'M', 'L']}</code>
+        enums <o> Enumerables, for example `{size: ['S', 'M', 'L']}`
         geo <b|false> If true, return combined area with totals
-        sort <[o]|[s]> Default sort, for example <code> ['+name', '-age']
+        sort <[o]|[s]> Default sort, for example `['+name', '-age']`
         sums <[s]> List of keys to be included in totals
         unique <s|'id'> The name of the unique key
     <script>
@@ -328,7 +328,7 @@ Ox.api = function(items, options) {
 };
 
 /*@
-Ox.compact <f> Removes <code>null</code> or <code>undefined</code> values
+Ox.compact <f> Removes `null` or `undefined` values
     (array) -> <a> Array 
     > Ox.compact([null,,1,,2,,3])
     [1, 2, 3]
@@ -434,14 +434,13 @@ Ox.makeArray = function(value) {
 /*@
 Ox.range <f> Python-style range
     (stop) -> <[n]> range
-        Returns an array of integers from <code>0</code> (inclusive) to
+        Returns an array of integers from `0` (inclusive) to `stop` (exclusive).
-        <code>stop</code> (exclusive).
     (start, stop) -> <[n]> range
-        Returns an array of integers from <code>start</code> (inclusive) to
+        Returns an array of integers from `start` (inclusive) to `stop`
-        <code>stop</code> (exclusive).
+        (exclusive).
     (start, stop, step) -> <[n]> range
-        Returns an array of numbers from <code>start</code> (inclusive) to
+        Returns an array of numbers from `start` (inclusive) to `stop`
-        <code>stop</code> (exclusive), incrementing by <code>step</code>.
+        (exclusive), incrementing by `step`.
     start <n> Start value
     stop <n> Stop value
     step <n> Step value

source/Ox/js/Collection.js

@@ -79,8 +79,7 @@ Ox.count = function(collection) {
 
 /*@
 Ox.every <f> Tests if every element of a collection satisfies a given condition
-    Unlike <code>[].every()</code>, <code>Ox.every()</code> works for arrays,
+    Unlike `[].every()`, `Ox.every()` works for arrays, objects and strings.
-    objects and strings.
     > Ox.every([0, 1, 2], function(v, i) { return v == i; })
     true
     > Ox.every({a: 1, b: 2, c: 3}, function(v) { return v == 1; })
@@ -98,8 +97,7 @@ Ox.every = function(collection, iterator) {
 
 /*@
 Ox.filter <f> Filters a collection by a given condition
-    Unlike <code>[].filter()</code>, <code>Ox.filter()</code> works for arrays,
+    Unlike `[].filter()`, `Ox.filter()` works for arrays, objects and strings.
-    objects and strings.
     > Ox.filter([2, 1, 0], function(v, i) { return v == i; })
     [1]
     > Ox.filter({a: 'c', b: 'b', c: 'a'}, function(v, k) { return v == k; })
@@ -129,12 +127,10 @@ Ox.filter = function(collection, iterator, that) {
 // FIXME: documentation is outdated!
 /*@
 Ox.forEach <f> forEach loop
-    <code>Ox.forEach()</code> loops over arrays, objects and strings.
+    `Ox.forEach()` loops over arrays, objects and strings. Returning `false`
-    Returning <code>false</code> from the iterator function acts like a
+    from the iterator function acts like a `break` statement (unlike
-    <code>break</code> statement (unlike <code>[].forEach()</code>, like
+    `[].forEach()`, like `$.each()`). The arguments of the iterator function are
-    <code>$.each()</code>). The arguments of the iterator function are
+    `(value, key, index)` (more like `[].forEach()` than like `$.each()`).
-    <code>(value, key, index)</code> (more like <code>[].forEach()</code>
-    than like <code>$.each()</code>).
     (collection, callback) <a|o|s> The collection
     (collection, callback, includePrototype) <a|o|s> The collection
     collection <a|o|s> An array, object or string
@@ -248,8 +244,8 @@ Ox.isEmpty = function(value) {
 
 /*@
 Ox.last <f> Gets or sets the last element of an array
-    Unlike <code>arrayWithALongName[arrayWithALongName.length - 1]</code>,
+    Unlike `arrayWithALongName[arrayWithALongName.length - 1]`,
-    <code>Ox.last(arrayWithALongName)</code> is short.
+    `Ox.last(arrayWithALongName)` is short.
     <script>
         Ox.test.array = [1, 2, 3];
     </script>
@@ -275,9 +271,8 @@ Ox.last = function(array, value) {
 
 /*@
 Ox.len <f> Returns the length of an array, node list, object or string
-    Not to be confused with <code>Ox.length</code>, which is the
+    Not to be confused with `Ox.length`, which is the `length` property of the
-    <code>length</code> property of the <code>Ox</code> function
+    `Ox` function (`1`).
-    (<code>1</code>).
     > Ox.len((function() { return arguments; }(1, 2, 3)))
     3
     > Ox.len([1, 2, 3])
@@ -309,8 +304,7 @@ Ox.len = function(collection) {
 
 /*@
 Ox.map <f> Transforms the values of an array, object or string
-    Unlike <code>[].map()</code>, <code>Ox.map()</code> works for arrays,
+    Unlike `[].map()`, `Ox.map()` works for arrays, objects and strings.
-    objects and strings.
     > Ox.map([2, 1, 0], function(v, i) { return v == i; })
     [false, true, false]
     > Ox.map({a: 'b', b: 'b', c: 'b'}, function(v, k) { return v == k; })
@@ -454,7 +448,7 @@ Ox.shuffle = function(collection) {
 };
 
 /*@
-Ox.slice <f> Alias for <code>Array.prototype.slice.call</code>
+Ox.slice <f> Alias for `Array.prototype.slice.call`
     > (function() { return Ox.slice(arguments, 1, -1); }(1, 2, 3))
     [2]
     > (function() { return Ox.slice(arguments, 1); }(1, 2, 3))
@@ -484,8 +478,7 @@ if (
 
 /*@
 Ox.some <f> Tests if one or more elements of a collection meet a given condition
-    Unlike <code>[].some()</code>, <code>Ox.some()</code> works for arrays,
+    Unlike `[].some()`, `Ox.some()` works for arrays, objects and strings.
-    objects and strings.
     > Ox.some([2, 1, 0], function(i, v) { return i == v; })
     true
     > Ox.some({a: 1, b: 2, c: 3}, function(v) { return v == 1; })