Tests for examples in embedded docs

[dvd101x]

Hi, this includes tests for the examples of the embedded docs according to #3391

[gwhitney]

OK, I checked out the branch and put an error in an example, and indeed the test failed. The code looks fine. So my only question before merging this is that it only runs the check for identifiers in embeddedDocs -- that's OK, we could put the test elsewhere that there is embeded documentation for every identifier callable from the expression evaluator -- but then it gives an identifier foo a pass if help("foo") throws an error. All of those help calls should succeed, and in fact all the tests pass if the try {...} catch { return } block around the evaluation of help("${name}") is removed. So I would strongly recommend removing that try - catch from this PR.

[dvd101x]

Nice catch!

Previously I was checking on math.expression.mathWithTranform and that try-catch was needed but not when checking directly on embeddedDocs.

Fixed it.

[dvd101x]

Also if we check for math.expression.mathWithTransform these are the ones that throws an error when calling math.evaluate("help(name)"). I don't know if they should be documented and maybe should be included in this PR.

• addScalar
• compile
• divideScalar
• equalScalar
• apply
• multiplyScalar
• not
• parse
• parser
• replacer
• reviver
• subtractScalar
• version

[gwhitney]

Thanks for the quick update.

Also if we check for math.expression.mathWithTransform these are the ones that throws an error when calling math.evaluate("help(name)"). I don't know if they should be documented and maybe should be included in this PR.

* `addScalar`, `divideScalar`, `equalScalar`, `multiplyScalar`, `subtractScalar`, `apply`

These are not really intended to be called by clients of the package, and so it's OK for them to be undocumented, and they can be recorded as such.

* `compile`, `not`, `parse`, `parser`, `version`

These should definitely be documented; I will leave it up to @josdejong whether he wants the addition of documentation to be part of this PR, and whether he wants to add a check that everything is documented besides exceptions like the above.

* `replacer`, `reviver`

I am less familiar with these so I will have to defer to @josdejong whether they are in the first or second category above. I think they have to do with JSON encoding and decoding.

[josdejong]

Thanks David, this is nice! I made one inline comment.

About the list with failing functions: Glen is right:

• No need for documentation:
  • addScalar, divideScalar, equalScalar, multiplyScalar, subtractScalar, apply
  • replacer, reviver they are indeed for serialization and not used inside the parser itself
• Needs documentation: compile, not, parse, parser, version.

I think the PR is small enough to directly add the missing documentation, I can help with that if needed.

[dvd101x]

Hi, thanks for the review.

Thanks Jos, please help me with the documentation for compile, parse, parser, version

Just a few comments:

• not was failing because I tested help(not) (which throws a syntax error) instead of help("not") in the parser, I will consider that.
• I will include also in the tests math.expression.mathWithTransform
• I will evaluate if the new math instance can be removed as mentioned in the inline comment.

[gwhitney]

• not was failing because I tested help(not) (which throws a syntax error) instead of help("not") in the parser, I will consider that.

I would consider this a bug in the parser, given that help(and) is totally fine. It is a consequence of the fact that not is the only "named" unary operator, and the parser does not contemplate that it might be used as an expression in and of itself, to mean the associated function. So similarly, map([true, false], not) is a syntax error, but I would say that it should be totally valid and return [false, true].

Should I file a separate bug for this? I could address it in #3423, for example. Alternatively, I should also point out that if a proposal along the lines of #3379 were adopted, it would also totally fix this, in that we would no longer need to consider not an operator; it would just be a function, and not x would be interpreted as function application, and it would work as expected. And once not is just a function, help(not) is fine. The precedence of not is also exactly correct for allowing it to be an ordinary function -- right alongside implicit multiplication, which is where this sort of function application would be defined. Frankly, I don't see any reason why not x should be allowed but sin x not be allowed. They actually seem completely parallel to me. I think consistency between not and other unary functions is another strong reason to adopt something like #3379.

[dvd101x]

As a reference, there was some discussion about it at #1905.

[gwhitney]

Ah, that's very helpful. I didn't realize that help(not) throwing had already been definitely classified as a bug. I would be happy to address it. I will continue discussion of it in #1905.