BrowseDoc: Support .browse files

examples/advanced/custom_rules.browse

@@ -24,7 +24,7 @@ rule while {
     # return is unncescessary since the result from the last rule in a RuleSet
     # is implicitly returned
     while $cond $body
-  } else { return null }
+  } else { return nil }
 }
 
 set i 0

packages/core/lib/std.js

@@ -680,6 +680,7 @@ const defRule = (evalRuleSet) => (scope) => (_opts) => (name, body) => {
         /**
          * @rule { bind }
          * @scope { rule }
+         * @parent { std }
          * @desc {
          *    **Only used within a {@link rule\} body**
          *    'bind' lets the rule accept arguments. Strings passed to bind are used to
@@ -725,6 +726,7 @@ const defRule = (evalRuleSet) => (scope) => (_opts) => (name, body) => {
         /**
          * @rule { return }
          * @scope { rule }
+         * @parent { std }
          * @desc {
          *    **Only used within a {@link rule\} body**
          *    'return' is often used to make the return value for a rule explicit. It's often

packages/core/stdlib/datetime/main.browse

@@ -1,14 +1,29 @@
+#* @name { DateTime }
+# @scope { DateTime utilities }
 import math
 
 import "./native.js"
 
-set SECOND 1000
-set MINUTE $SECOND * 60
-set HOUR $MINUTE * 60
-set DAY $HOUR * 24
-set WEEK $DAY * 7
+#* Number of seconds in a minute
+set SECONDS_PER_MINUTE 60
+#* Number of minutes in an hour
+set MINUTES_PER_HOUR 60
+#* Number of hours in a day
+set HOURS_PER_DAY 24
+#* Number of days in a week
 set DAYS_PER_WEEK 7
 
+#* Number of milliseconds in a second
+set SECOND 1000
+#* Number of milliseconds in a minute
+set MINUTE $SECOND * $SECONDS_PER_MINUTE
+#* Number of milliseconds in an hour
+set HOUR $MINUTE * $MINUTES_PER_HOUR
+#* Number of milliseconds in a day
+set DAY $HOUR * $HOURS_PER_DAY
+#* Number of milliseconds in a week
+set WEEK $DAY * $DAYS_PER_WEEK
+
 # A date looks like this:
 # dict { _ __type__ 'Date' ; _ value number }
 # `value` is in epoch ms
@@ -21,50 +36,78 @@ rule Date { bind a b c d e f g; return (native:Date $a $b $c $d $e $f $g) }
 ####################################
 ### The Native JS Date functions ###
 ####################################
+#* Returns the day of the month (1–31) for the specified date according to local time.
 rule getDate { bind date; return (native:date_fn $date getDate) }
+#* Returns the day of the week (0–6) for the specified date according to local time.
 rule getDay { bind date; return (native:date_fn $date getDay) }
+#* Returns the day of the week (0–6) for the specified date according to local time.
 rule getFullYear { bind date; return (native:date_fn $date getFullYear) }
+#* Returns the hour (0–23) in the specified date according to local time.
 rule getHours { bind date; return (native:date_fn $date getHours) }
+#* Returns the milliseconds (0–999) in the specified date according to local time.
 rule getMilliseconds {
   bind date; return (native:date_fn $date getMilliseconds)
 }
+#* Returns the minutes (0–59) in the specified date according to local time.
 rule getMinutes { bind date; return (native:date_fn $date getMinutes) }
+#* Returns the month (0–11) in the specified date according to local time.
 rule getMonth { bind date; return (native:date_fn $date getMonth) }
+#* Returns the seconds (0–59) in the specified date according to local time.
 rule getSeconds { bind date; return (native:date_fn $date getSeconds) }
+#* Returns the numeric value of the specified date as the number of milliseconds since January 1, 1970, 00:00:00 UTC. (Negative values are returned for prior times.)
 rule getTime { bind date; return (native:date_fn $date getTime) }
+#* Returns the time-zone offset in minutes for the current locale.
 rule getTimezoneOffset {
   bind date; return (native:date_fn $date getTimezoneOffset)
 }
+#* Returns the day (date) of the month (1–31) in the specified date according to universal time.
 rule getUTCDate { bind date; return (native:date_fn $date getUTCDate) }
+#* Returns the day of the week (0–6) in the specified date according to universal time.
 rule getUTCDay { bind date; return (native:date_fn $date getUTCDay) }
+#* Returns the year (4 digits for 4-digit years) in the specified date according to universal time.
 rule getUTCFullYear { bind date; return (native:date_fn $date getUTCFullYear) }
+#* Returns the hours (0–23) in the specified date according to universal time.
+rule getUTCHours { bind date; return (native:date_fn $date getUTCHours) }
+#* Returns the milliseconds (0–999) in the specified date according to universal time.
 rule getUTCMilliseconds {
   bind date; return (native:date_fn $date getUTCMilliseconds)
 }
+#* Returns the minutes (0–59) in the specified date according to universal time.
 rule getUTCMinutes { bind date; return (native:date_fn $date getUTCMinutes) }
+#* Returns the month (0–11) in the specified date according to universal time.
 rule getUTCMonth { bind date; return (native:date_fn $date getUTCMonth) }
+#* Returns the seconds (0–59) in the specified date according to universal time.
 rule getUTCSeconds { bind date; return (native:date_fn $date getUTCSeconds) }
+#* Returns the "date" portion of the Date as a human-readable string like 'Thu Apr 12 2018'.
 rule toDateString { bind date; return (native:date_fn $date toDateString) }
+#* Converts a date to a string following the ISO 8601 Extended Format.
 rule toISOString { bind date; return (native:date_fn $date toISOString) }
+#* Returns a string with a locality sensitive representation of the date portion of this date based on system settings.
 rule toLocaleDateString {
   bind date tz; return (native:date_fn $date toLocaleDateString $tz)
 }
+#* Returns a string with a locality-sensitive representation of this date
 rule toLocaleString {
   bind date tz; return (native:date_fn $date toLocaleString $tz)
 }
+#* Returns a string with a locality-sensitive representation of the time portion of this date, based on system settings.
 rule toLocaleTimeString {
   bind date tz; return (native:date_fn $date toLocaleTimeString $tz)
 }
+#* Returns a string representing the specified Date object
 rule toString { bind date; return (native:date_fn $date toString) }
+#* Returns the "time" portion of the Date as a human-readable string.
 rule toTimeString { bind date; return (native:date_fn $date toTimeString) }
+#* Converts a date to a string using the UTC timezone.
 rule toUTCString { bind date; return (native:date_fn $date toUTCString) }
+#* Returns the primitive value of a Date object
 rule valueOf { bind date; return (native:date_fn $date valueOf) }
 
 #####################################
 ### Porting the golib/deno stdlib ###
 #####################################
 
-# Get number of the day in the year
+#* Get number of the day in the year
 # @return Number of the day in year
 rule dayOfYear {
   bind date

packages/core/stdlib/math/main.browse

@@ -1,12 +1,29 @@
+#* @scope { Standard Math functions }
+#  @name { Math }
 import "./native.js"
 
+#* Euler's constant and the base of natural logarithms; approximately 2.718.
 set E 2.718281828459045
+
+#* Natural logarithm of 2; approximately 0.693.
 set LN10 2.302585092994046
+
+#* Natural logarithm of 10; approximately 2.303.
 set LN2 0.6931471805599453
+
+#* Base-2 logarithm of E; approximately 1.443.
 set LOG10E 0.4342944819032518
+
+#* Base-10 logarithm of E; approximately 0.434.
 set LOG2E 1.4426950408889634
+
+#* Ratio of the a circle's circumference to its diameter; approximately 3.14159.
 set PI 3.141592653589793
+
+#* Square root of ½ (or equivalently, 1/√2); approximately 0.707.
 set SQRT1_2 0.7071067811865476
+
+#* Square root of 2; approximately 1.414.
 set SQRT2 1.4142135623730951
 
 # built in number functions
@@ -22,41 +39,76 @@ rule toPrecision {
 }
 
 # Math.* fns
+#* Returns the absolute value of x.
 rule abs { bind x; return (native:fn abs $x) }
+#* Returns the arccosine of x.
 rule acos { bind x; return (native:fn acos $x) }
+#* Returns the hyperbolic arccosine of x.
 rule acosh { bind x; return (native:fn acosh $x) }
+#* Returns the arcsine of x.
 rule asin { bind x; return (native:fn asin $x) }
+#* Returns the hyperbolic arcsine of a number.
 rule asinh { bind x; return (native:fn asinh $x) }
+#* Returns the arctangent of x.
 rule atan { bind x; return (native:fn atan $x) }
+#* Returns the hyperbolic arctangent of x.
 rule atanh { bind x; return (native:fn atanh $x) }
+#* Returns the arctangent of the quotient of its arguments.
 rule atan2 { bind y x; return (native:fn atan2 $y $x) }
-rule cbrt { bind x; return (native:fn cbrt $x) }
+#* Returns the cube root of x.
+rule cbrt { bind x; return (native:fn cbrt $x) }a
+#* Returns the smallest integer greater than or equal to x.
 rule ceil { bind x; return (native:fn ceil $x) }
+#* Returns the number of leading zeroes of the 32-bit integer x.
 rule clz32 { bind x; return (native:fn clz32 $x) }
+#* Returns the cosine of x.
 rule cos { bind x; return (native:fn cos $x) }
+#* Returns the hyperbolic cosine of x.
 rule cosh { bind x; return (native:fn cosh $x) }
+#* Returns E^x, where x is the argument, and E is Euler's constant (2.718…, the base of the natural logarithm).
 rule exp { bind x; return (native:fn exp $x) }
+#* Returns subtracting 1 from exp(x).
 rule expm1 { bind x; return (native:fn expm1 $x) }
+#* Returns the largest integer less than or equal to x.
 rule floor { bind x; return (native:fn floor $x) }
+#* Returns the nearest single precision float representation of x.
 rule fround { bind x; return (native:fn fround $x) }
+#* Returns the square root of the sum of squares of both arguments.
 # TODO: support more than 2 arguments, like in the JS native version
 rule hypot { bind x y; return (native:fn hypot $x $y) }
+#* Returns the result of the 32-bit integer multiplication of x and y.
 rule imul { bind x y; return (native:fn imul $x $y) }
+#* Returns the natural logarithm (㏒e; also, ㏑) of x.
 rule log { bind x; return (native:fn log $x) }
+#* Returns the natural logarithm (㏒e; also ㏑) of 1 + x for the number x.
 rule log1p { bind x; return (native:fn log1p $x) }
+#* Returns the base-10 logarithm of x.
 rule log10 { bind x; return (native:fn log10 $x) }
+#* Returns the base-2 logarithm of x.
 rule log2 { bind x; return (native:fn log2 $x) }
 # TODO: support more than 2 arguments, like in the JS native version
+#* Returns the largest of x and y numbers.
 rule max { bind x y; return (native:fn max $x $y) }
 # TODO: support more than 2 arguments, like in the JS native version
+#* Returns the smallest of x and y.
 rule min { bind x y; return (native:fn min $x $y) }
+#* Returns base x to the exponent power y (that is, xy).
 rule pow { bind x y; return (native:fn pow $x $y) }
+#* Returns a pseudo-random number between 0 and 1.
 rule random { return (native:fn random) }
+#* Returns the value of the number x rounded to the nearest integer.
 rule round { bind x; return (native:fn round $x) }
+#* Returns the sign of the x, indicating whether x is positive, negative, or zero.
 rule sign { bind x; return (native:fn sign $x) }
+#* Returns the sine of x.
 rule sin { bind x; return (native:fn sin $x) }
+#* Returns the hyperbolic sine of x.
 rule sinh { bind x; return (native:fn sinh $x) }
+#* Returns the positive square root of x.
 rule sqrt { bind x; return (native:fn sqrt $x) }
+#* Returns the tangent of x.
 rule tan { bind x; return (native:fn tan $x) }
+#* Returns the hyperbolic tangent of x.
 rule tanh { bind x; return (native:fn tanh $x) }
+#* Returns the integer portion of x, removing any fractional digits.
 rule trunc { bind x; return (native:fn trunc $x) }

packages/docs/index.js

@@ -44,6 +44,7 @@ const main = async () => {
                 ),
               ];
             } else if (ext === ".browse") {
+              console.log(`Parsing ${directory}/${file}`);
               const stem = path.basename(file, ".browse");
               return [
                 stem,
@@ -65,7 +66,9 @@ const main = async () => {
 
   const outputs = await Promise.all(
     pages.map(([stem, doc]) =>
-      markdownPlugin(doc, path.join(outPath, stem + ".md"))
+      Object.keys(doc).map((scope) =>
+        markdownPlugin(doc, path.join(outPath, scope + ".md"))
+      )
     )
   );