Fix a couple documentation punctuation errors #3233

Merged
merged 4 commits into from Jan 2, 2015

Conversation

Projects
None yet
4 participants
@jessepinho
Contributor

jessepinho commented Dec 24, 2014

No description provided.

site/_docs/plugins.md
@@ -68,8 +68,8 @@ A generator is a subclass of `Jekyll::Generator` that defines a `generate`
method, which receives an instance of
[`Jekyll::Site`]({{ site.repository }}/blob/master/lib/jekyll/site.rb).
-Generation is triggered for its side-effects, the return value of `generate` is
-ignored. Jekyll does not assume any particular side-effect to happen, it just
+Because generation is triggered for its side effects, the return value of `generate` is

This comment has been minimized.

@parkr

parkr Dec 25, 2014

Member

I'm really not comfortable starting a sentence with because. Would you be willing to rework this to avoid that?

@parkr

parkr Dec 25, 2014

Member

I'm really not comfortable starting a sentence with because. Would you be willing to rework this to avoid that?

@parkr

This comment has been minimized.

Show comment
Hide comment
@parkr

parkr Dec 25, 2014

Member

Thank you! Just one comment.

Member

parkr commented Dec 25, 2014

Thank you! Just one comment.

site/_docs/plugins.md
-runs the method.
+The return value of `generate` is ignored, since generation is triggered for
+its side effects. Jekyll does not expect any particular side effect to
+happen---it just runs the method.

This comment has been minimized.

@jessepinho

jessepinho Dec 25, 2014

Contributor

@parkr Sure! What do you think of this change?

@jessepinho

jessepinho Dec 25, 2014

Contributor

@parkr Sure! What do you think of this change?

This comment has been minimized.

@parkr

parkr Dec 25, 2014

Member

Reading through the original verbiage, it sounds like a very long way of saying "Jekyll asserts no expectations about the effects nor return value of this method." What do you think about that?

@parkr

parkr Dec 25, 2014

Member

Reading through the original verbiage, it sounds like a very long way of saying "Jekyll asserts no expectations about the effects nor return value of this method." What do you think about that?

This comment has been minimized.

@jessepinho

jessepinho Dec 25, 2014

Contributor

I think it's important to explicitly note that Jekyll ignores the return value of generate. Other than that, the verbiage about not "expect[ing] any particular side effect to happen" is kind of confusing—I'm not sure what the original author meant by that. It seems kind of self-explanatory that a method would be run for its effects—in fact, "side effect" is probably misleading—so I actually think it makes more sense to take the first sentence and group it with the previous paragraph, and then remove the second sentence:

...

A generator is a subclass of Jekyll::Generator that defines a generate method, which receives an instance of Jekyll::Site. The return value of generate is ignored.

Generators run after Jekyll has made an inventory ...

@jessepinho

jessepinho Dec 25, 2014

Contributor

I think it's important to explicitly note that Jekyll ignores the return value of generate. Other than that, the verbiage about not "expect[ing] any particular side effect to happen" is kind of confusing—I'm not sure what the original author meant by that. It seems kind of self-explanatory that a method would be run for its effects—in fact, "side effect" is probably misleading—so I actually think it makes more sense to take the first sentence and group it with the previous paragraph, and then remove the second sentence:

...

A generator is a subclass of Jekyll::Generator that defines a generate method, which receives an instance of Jekyll::Site. The return value of generate is ignored.

Generators run after Jekyll has made an inventory ...

@parkr parkr added the Documentation label Dec 27, 2014

@mattr- mattr- merged commit 8d968eb into jekyll:master Jan 2, 2015

1 check passed

continuous-integration/travis-ci The Travis CI build passed
Details

mattr- added a commit that referenced this pull request Jan 2, 2015

@jessepinho jessepinho deleted the jessepinho:punctuation-fixes branch Jan 2, 2015

@jekyll jekyll locked and limited conversation to collaborators Feb 27, 2017

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