search

google / cel-spec

Common Expression Language -- specification and binary representation
https://cel.dev
Apache License 2.0
2.78k stars 222 forks source link

Add examples in the "standard definitions" table #213

Open francislavoie opened 2 years ago

francislavoie commented 2 years ago

Every time I find myself referencing the spec, language definition doc, I have a hard time figuring out how each of the standard definitions can actually be used, because they just talk about an operator/function, but without context.

https://github.com/google/cel-spec/blob/master/doc/langdef.md#list-of-standard-definitions

I'd like to see examples for as many of the entries in that table as possible, in the description column. For example, it took me a while to figure out that a string -> int cast is done by doing int("string"), when I might've guessed it might be (int) "string" like in some C-like languages.

For the symbols column I think code styling should be used (backticks in markdown) to use a monospaced font, because some of the entries like _[_] are hard to read on their own, it would look better as _[_].

A note that _ means "where the operands go" would help clarify as well, I didn't find that immediately obvious.

TristonianJones commented 2 years ago

@francislavoie Good feedback, we definitely need to overhaul the builtin function docs.

ardunster commented 11 months ago

This issue is two years old, and yet I still find the documentation less useful than just looking through your test files to see what functions are available and how to use them. Which I don't find convenient, so that's saying something.

TristonianJones commented 11 months ago

@ardunster you're right. We're working on overhauling docs now actually.