empty? should be documented more clearly.

[amano-kenji]

repl:1:> (doc empty?)


    function
    boot.janet on line 117, column 1

    (empty? xs)

    Check if xs is empty.

What? Define empty. I thought nil was empty.

[kenaryn]

nil is derived from latin nihil which approximately stands for "no thing". There is no thing (pun intended) like emptyness. Even the cosmic void is filled with reversed Kasimir force (formerly known as dark matter then more recently as dark energy).

I think the Janet doc means "Check if xs has a null valence ( from latin ne ullus, "not one") if I were to use array theory terminology.
I know Janet is not based on Array paradigm (unlike a language like Nial) so perhaps Check if xs has a zero dimensionality could be adopted in stead...

... or even "Check if xs has a null length".

[amano-kenji]

Define xs.

[oneness]

xs in janet (in version 1.34 that I verified) means iterables. While I agree docs could be improved, I really like Janets error reporting, which is self explanatory.

[sogaiu]

It is true that it's not spelled out explicitly what xs represents all of the time.

For reference, this seems to be the case in the docstrings for the following as well: %, %=, *, *=, +, -, /, <, <=, =, >=, array/insert, array/push, band, bor, buffer, buffer/push, buffer/push-at, buffer/push-byte, buffer/push-string, buffer/push-word, bxor, compare<, compare<=, compare=, compare>, compare>=, distinct, div, eprin, eprinf, eprint, eprintf, geomean, last, mean, mod, not=, prin, prinf, print, printf, product, string, sum, symbol, tuple/brackets, xprin, xprinf, xprint, and xprintf.

[sogaiu]

I've gone over the list above and based on each of the corresponding docstrings, I don't think it's unclear what xs (or in one case ns) means for the following:

• % %= * *= + - / < <= = >=
• array/insert array/push
• band bor bxor
• buffer buffer/push buffer/push-at buffer/push-byte buffer/push-string buffer/push-word
• compare< compare<= compare= compare> compare>=
• div mod
• eprin eprinf eprint eprintf
• not=
• prin prinf print printf
• string
• symbol
• tuple/brackets
• xprin xprinf xprint xprintf

FWIW, these all have have signatures that contain & xs (or & ns) and I think the docstring content gives enough context for one to arrive at an appropriate interpretation.

---

For geomean, mean, product, sum, distinct I think a straight-forward interpretation would include xs covering at least an indexed type (so arrays and tuples) [1].

---

For last, the docstring explicitly mentions "indexed data structure" and there is only one argument, so deducing that xs is supposed to be an indexed data structure seems reasonable to me.

---

[1] All of the implementations have bits that refer to each, so whatever works with each may work -- though there is no claim of this in the docstring so I would stick with indexed types to be on the same side, YMMV.