Possible error in documentation for .traverse ?

[JacobBeaudry]

I was just going over the documentation for the traverse method provided in index.d and noticed the following:

... The callback function is a mapping
* function accepting a node, and returning a replacement for the node
* or the original node.

however, it is typed as:

  traverse(
      callback: (node: MathNode, path: string, parent: MathNode) => void
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
    ): any

i.e. traverse seems to execute a callback function that does not return anything.

Let me know if flagging these kinds of things is useful (and, if so, if there is any preferred method / format / place for doing so).

[josdejong]

Thanks, yes, these kind of reports are very useful!

This is indeed a bug in the TypeScript definitions. I'll fix this one right away.

[josdejong]

if there is any preferred method / format / place for doing so

This is a bug, the best place for that is the issues section: https://github.com/josdejong/mathjs/issues
The Discussions section is best for discussing general ideas, suggestions, and questions

[JacobBeaudry]

This is a bug, the best place for that is the issues section: https://github.com/josdejong/mathjs/issues
The Discussions section is best for discussing general ideas, suggestions, and questions

I just wasn't certain whether this was a bug or a mistake in the documentation and wasn't sure if it was more inconvenient to have a bug report in place of a discussion or a discussion in place of a bug report. Either way, I'm happy to covert one to the other, after the fact, if that would be helpful! Hope all is well on your end!

[JacobBeaudry]

This is indeed a bug in the TypeScript definitions. I'll fix this one right away.

I wasn't expecting it to be an issue with the way it was typed, I really thought it was a mistake in the documentation, because the documentation for .traverse also says (emphasis added):

Recursively traverse all nodes in a node tree. Executes given callback for this node and each of its child nodes. Similar to Array.forEach, except recursive.

and .forEach's documentation doesn't mention anything about the callback function having to return a node or replacement node:

forEach(callback: function) : Node[]
Execute a callback for each of the child nodes of this node. The callback function is called as callback(child: Node, path: string,
parent: Node). Parameter path is a string containing a relative JSON Path.

See also traverse, which is a recursive version of forEach.

Does this mean that the documentation for .forEach is incorrect? The typescript there also suggests that it can return any, not a MathNode specifically:

/**
     * [forEach description]
     */
    forEach(
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      callback: (node: MathNode, path: string, parent: MathNode) => any
    ): MathNode[]

I just noticed that it also lists the return type of .forEach as MathNode[]^A, which doesn't seem right. If it's meant to be analogous to Array.prototype.forEach(), I believe the return type should be void.

A: This seems to echo the pseudo-typescript on the inline code introducing forEach's documentation (i.e. forEach(callback: function): Node[]).

[josdejong]

Ouch, that is really confusing indeed. The docs and types of forEach are indeed wrong: it does not return anything. The docs on forEach have been there like that for 8 years 😳.

I've corrected this now in the develop branch via b050d5e.

[josdejong]

The fixes in the docs and types are published now in v11.4.0