From 2769a62bb35c2d65b424ece92c6ded5b77f25b9b Mon Sep 17 00:00:00 2001 From: John Gabriele Date: Sat, 24 Jul 2021 16:58:21 -0400 Subject: [PATCH 1/2] Add some clarifying backticks to docs --- src/core/array.c | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/src/core/array.c b/src/core/array.c index 8e1e3f6b..c697fa97 100644 --- a/src/core/array.c +++ b/src/core/array.c @@ -307,12 +307,12 @@ static const JanetReg array_cfuns[] = { { "array/new-filled", cfun_array_new_filled, JDOC("(array/new-filled count &opt value)\n\n" - "Creates a new array of count elements, all set to value, which defaults to nil. Returns the new array.") + "Creates a new array of `count` elements, all set to `value`, which defaults to nil. Returns the new array.") }, { "array/fill", cfun_array_fill, JDOC("(array/fill arr &opt value)\n\n" - "Replace all elements of an array with value (defaulting to nil) without changing the length of the array. " + "Replace all elements of an array with `value` (defaulting to nil) without changing the length of the array. " "Returns the modified array.") }, { @@ -334,7 +334,7 @@ static const JanetReg array_cfuns[] = { { "array/ensure", cfun_array_ensure, JDOC("(array/ensure arr capacity growth)\n\n" - "Ensures that the memory backing the array is large enough for capacity " + "Ensures that the memory backing the array is large enough for `capacity` " "items at the given rate of growth. Capacity and growth must be integers. " "If the backing capacity is already enough, then this function does nothing. " "Otherwise, the backing memory will be reallocated so that there is enough space.") @@ -342,34 +342,34 @@ static const JanetReg array_cfuns[] = { { "array/slice", cfun_array_slice, JDOC("(array/slice arrtup &opt start end)\n\n" - "Takes a slice of array or tuple from start to end. The range is half open, " - "[start, end). Indexes can also be negative, indicating indexing from the end of the " - "end of the array. By default, start is 0 and end is the length of the array. " - "Note that index -1 is synonymous with index (length arrtup) to allow a full " + "Takes a slice of array or tuple from `start` to `end`. The range is half open, " + "[start, end). Indexes can also be negative, indicating indexing from the " + "end of the array. By default, `start` is 0 and `end` is the length of the array. " + "Note that index -1 is synonymous with index `(length arrtup)` to allow a full " "negative slice range. Returns a new array.") }, { "array/concat", cfun_array_concat, JDOC("(array/concat arr & parts)\n\n" - "Concatenates a variable number of arrays (and tuples) into the first argument " + "Concatenates a variable number of arrays (and tuples) into the first argument, " "which must be an array. If any of the parts are arrays or tuples, their elements will " - "be inserted into the array. Otherwise, each part in parts will be appended to arr in order. " - "Return the modified array arr.") + "be inserted into the array. Otherwise, each part in `parts` will be appended to `arr` in order. " + "Return the modified array `arr`.") }, { "array/insert", cfun_array_insert, JDOC("(array/insert arr at & xs)\n\n" - "Insert all xs into array arr at index at. at should be an integer between " - "0 and the length of the array. A negative value for at will index backwards from " + "Insert all `xs` into array `arr` at index `at`. `at` should be an integer between " + "0 and the length of the array. A negative value for `at` will index backwards from " "the end of the array, such that inserting at -1 appends to the array. " "Returns the array.") }, { "array/remove", cfun_array_remove, JDOC("(array/remove arr at &opt n)\n\n" - "Remove up to n elements starting at index at in array arr. at can index from " - "the end of the array with a negative index, and n must be a non-negative integer. " - "By default, n is 1. " + "Remove up to `n` elements starting at index `at` in array `arr`. `at` can index from " + "the end of the array with a negative index, and `n` must be a non-negative integer. " + "By default, `n` is 1. " "Returns the array.") }, { From 76acbf9bb656b27ed21d4327d6e0a9b094211ce0 Mon Sep 17 00:00:00 2001 From: John Gabriele Date: Sat, 24 Jul 2021 18:44:49 -0400 Subject: [PATCH 2/2] Clarify docs on take and drop functions Pass in indexed and bytes, return tuples and strings, respectively. --- src/boot/boot.janet | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/boot/boot.janet b/src/boot/boot.janet index d7e1bbe2..45377a5e 100644 --- a/src/boot/boot.janet +++ b/src/boot/boot.janet @@ -1027,7 +1027,7 @@ ret) (defn take - "Take first n elements in an indexed type. Returns new indexed instance." + "Take the first n elements of an indexed or bytes type. Returns a new tuple or string, respectively." [n ind] (def use-str (bytes? ind)) (def f (if use-str string/slice tuple/slice)) @@ -1038,7 +1038,7 @@ (f ind 0 end)) (defn take-until - "Same as (take-while (complement pred) ind)." + "Same as `(take-while (complement pred) ind)`." [pred ind] (def use-str (bytes? ind)) (def f (if use-str string/slice tuple/slice)) @@ -1048,13 +1048,14 @@ (f ind 0 end)) (defn take-while - `Given a predicate, take only elements from an indexed type that satisfy - the predicate, and abort on first failure. Returns a new array.` + `Given a predicate, take only elements from an indexed or bytes type that satisfy + the predicate, and abort on first failure. Returns a new tuple or string, respectively.` [pred ind] (take-until (complement pred) ind)) (defn drop - "Drop first n elements in an indexed type. Returns new indexed instance." + ``Drop the first n elements in an indexed or bytes type. Returns a new tuple or string + instance, respectively.`` [n ind] (def use-str (bytes? ind)) (def f (if use-str string/slice tuple/slice)) @@ -1065,7 +1066,7 @@ (f ind start -1)) (defn drop-until - "Same as (drop-while (complement pred) ind)." + "Same as `(drop-while (complement pred) ind)`." [pred ind] (def use-str (bytes? ind)) (def f (if use-str string/slice tuple/slice)) @@ -1075,8 +1076,8 @@ (f ind start)) (defn drop-while - `Given a predicate, remove elements from an indexed type that satisfy - the predicate, and abort on first failure. Returns a new array.` + `Given a predicate, remove elements from an indexed or bytes type that satisfy + the predicate, and abort on first failure. Returns a new tuple or string, respectively.` [pred ind] (drop-until (complement pred) ind))