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

Switch to ruby-style function parameters in documentation #1975

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
2 participants
@awwaiid
Contributor

awwaiid commented Oct 22, 2018

There are many places where lisp-style function invocation syntax is
used in the documentation. This clearly works, but the semantics are
confusing to a novice (based on watching people learn SonicPi without
knowing Ruby, and in some cases even when they DO know Ruby). This is
more pronounced when the result is then method-chained, which is
frequent.

This changes documentation like:
(ring 10, 20, 30, 40, 50).shuffle.drop(1).take(3)
to:
ring(10, 20, 30, 40, 50).shuffle.drop(1).take(3)

I will not be offended if this suggested change is rejected :)

Switch to ruby-style function parameters in documentation
There are many places where lisp-style function invocation syntax is
used in the documentation. This clearly works, but the semantics are
confusing to a novice (based on watching people learn SonicPi without
knowing Ruby, and in some cases even when they DO know Ruby). This is
more pronounced when the result is then method-chained, which is
frequent.
@samaaron

This comment has been minimized.

Owner

samaaron commented Oct 26, 2018

Thanks for this, but the lisp style for rings is purposeful - both to indicate that they're a list-like data structure like an array and also to ensure that kids aren't scared by parens at the starting position later in life :-)

@samaaron samaaron closed this Oct 26, 2018

@awwaiid

This comment has been minimized.

Contributor

awwaiid commented Oct 26, 2018

Well, it was worth a try :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment