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

Small fixes for let and do in Syntax.md #69

Merged
merged 10 commits into from
Apr 24, 2017

Conversation

andreasthoelke
Copy link
Contributor

Small fixes in the let and do documentation.

Copy link
Collaborator

@hdgarrood hdgarrood left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is looking great so far!

@@ -402,7 +402,7 @@ conditional = if 2 > 1 then "ok" else "oops"

## Let and where bindings

The `let` keyword a collection of local declarations, which may be mutually recursive, and which may include type declarations:
The `let` keyword defines a collection of local declarations, which may be mutually recursive, and which may include type declarations:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd prefer "introduces" rather than "defines" here; what does everyone else think?

@chexxor
Copy link
Collaborator

chexxor commented Apr 23, 2017

I would only change it if defines is wrong. Thanks for fixing this, BTW!

@hdgarrood
Copy link
Collaborator

I think "defines" is wrong — the keyword can't really define anything by itself, it's just a keyword. I guess I was really asking if anyone can think of any better alternatives to my suggestion.

@andreasthoelke
Copy link
Contributor Author

I agree that "defines" is not correct.
"The let keyword introduces a collection of local declarations, .." is fine, I think.

@hdgarrood
Copy link
Collaborator

@andreasthoelke Thanks very much! This looks good to merge now as far as I can tell, was there anything else you think wants doing or should I go ahead and merge?

@andreasthoelke
Copy link
Contributor Author

When reading the descriptions of let and where in conjunction, I noticed that the current version is not making the difference too clear.

We could go:

let expressions introduce a list of local declarations (variable bindings?), which may be mutually recursive, and which may include type declarations:
..

where clauses can be added at the end of a function declaration, and allow to bind variables (set up declarations) that are visible within the surrounding function context.

@@ -402,7 +402,7 @@ conditional = if 2 > 1 then "ok" else "oops"

## Let and where bindings

The `let` keyword a collection of local declarations, which may be mutually recursive, and which may include type declarations:
`let` expressions encompass a list of local declarations, which may be mutually recursive, and which may include type declarations:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer the previous version with "The let keyword introduces a collection of local declarations...", actually.

@@ -415,13 +415,13 @@ factorial =
go 1
```

The `where` keyword can also be used to introduce local declarations at the end of a value declaration:
`where` clauses can be added at the end of a function declaration, and allow to bind variables that are visible throughout the function:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this sentence was okay before; what was your reasoning behind this change?

Copy link
Collaborator

@hdgarrood hdgarrood Apr 24, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Specifically, it's incorrect to say "function declarations", you can also do e.g.

pi :: Number
pi = 4.0 * (sum (take 100 (taylorSeries arctan 1.0))
  where
  taylorSeries = [...]
  arctan = [...]

It would be incorrect to call this a "function declaration" because it isn't declaring a function; you can use a where clause in any kind of value declaration which is why "value declaration" is preferable. Also, "... allow to bind variables ..." is grammatically incorrect. Most importantly though, I think it would be best to make the structure of this sentence resemble that of the earlier sentence that tells you what the let keyword does as much as we reasonably can, so that it's as clear as possible that let and where do basically the same thing.

@hdgarrood
Copy link
Collaborator

I'm not really sure what this latest iteration adds over what we had previously, ideally I think we would just add "introduces" to the let sentence and leave the where sentence as-is. Can we please just do that for now, and then potentially discuss further wording changes in a separate PR? Just because the rest of the changes are clearly ready to go now and everyone agrees on them.

@hdgarrood
Copy link
Collaborator

Great, thanks very much :)

@andreasthoelke
Copy link
Contributor Author

Ok, I changed this back.

@hdgarrood hdgarrood merged commit 1015882 into purescript:master Apr 24, 2017
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

Successfully merging this pull request may close these issues.

None yet

3 participants