Many methods in Any docs are wrong

[zoffixznet]

Many, if not most, methods in Any docs are either slightly wrong or are outright completely invalid.

Briefly scanning the docs I see these issues:

• method produce - this one is just plain missing.
• method reduce - missing.
• method rotor - missing
• "Treats the Any as a 1-item list" — many methods mention this, however the actual behaviour is the Any gets coerced to a list using .list method, which is a 1-item list if Any.list is used, but some types implement their own .list. For example ^10 .combinations would treat that Range as a list, but the docs suggest the Range would become a single item
• "Coerce the invocant first to a List" — the actual coercion for many methods is to a "list" (lowercase), using .list method which can give any Positional
• "Returns an empty List." / "Returns Any." / etc. — this is the "completely invalid" category. Some methods like .pairs, .antipairs, and .kv seem to document observed behaviour for an Any typeobject rather than what the methods actually do. Yes, Any.pairs returns an empty list, but the behaviour for Any:D is to coerce to .list and then call .pairs on the result.
• method values.
• say Any.flatmap
• say Any.skip
• say Any.first
• say Any.unique
• say Any.repeated
• say Any.squish
• say Any.categorize
• say Any.classify
• say Any.pairs
• say Any.kv
• say Any.tree
• say Any.nl-out
• say Any.invert
• say Any.combinations
• Any.map and sub map

There may be more issues and my suggestion would be to look through all the methods to ensure they contain valid information.

[JJ]

If I can be of help, do assign me some issue. Are you working on this?

[zoffixznet]

Are you working on this?

Not me, no.

[JJ]

OK, I'll try to have a look at it then.

[JJ]

However, there is still a problem, and that is my usual concern with examples, in that they do not reflect a real use case. Using a class name like Any in examples like say Any.roll, and correct me if I'm wrong, converts class Any to an object of type Any and then applies roll. Wouldn't it be more adequate to use, say, a list of objects with classes that descend from Any and apply one of these examples to them?
Besides, flatmap is discouraged in list. Shouldn't we mention this also here? Or at least make a reference to that?

[JJ]

Great work, @fluca1978

[JJ]

Reopening this, since many examples still document what happens if you call the method on Any, the class, instead of an object of any class in the Any hierarchy. Search for say Any. in the document and try to eliminate all of them.

[JJ]

In some cases, those methods are described again where they make sense (in List, for instance). Insert a reference to them in that case.

[JJ]

Reopen to address #2675