Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add examples in the "standard definitions" table #213

Open
francislavoie opened this issue Oct 20, 2021 · 3 comments
Open

Add examples in the "standard definitions" table #213

francislavoie opened this issue Oct 20, 2021 · 3 comments

Comments

@francislavoie
Copy link

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
Copy link
Collaborator

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

@ardunster
Copy link

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
Copy link
Collaborator

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants
@TristonianJones @francislavoie @ardunster and others