Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

docs(angular.module): simplify wording #12543

Closed
wants to merge 3 commits into from
Closed

docs(angular.module): simplify wording #12543

wants to merge 3 commits into from

Conversation

frankadrian
Copy link
Contributor

A suggestion on the wording of retrieving a moudle

A suggestion on the wording of retrieving a moudle
@googlebot
Copy link

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project, in which case you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.


  • If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
  • If you signed the CLA as a corporation, please let us know the company's name.

@frankadrian
Copy link
Contributor Author

signed

@@ -39,7 +39,7 @@ function setupModuleLoader(window) {
* registered using this mechanism.
*
* When passed two or more arguments, a new module is created. If passed only one argument, an
* existing module (the name passed as the first argument to `module`) is retrieved.
* existing module of that name is retrieved.
Copy link
Contributor

Choose a reason for hiding this comment

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

I like that this is concise --- but how about we make it clear that we're talking about a specific parameter, and maybe just reword the paragraph entirely, because it wasn't particularly well written to begin with. It sounds sort of Yoda-ish, you know? (Referring especially to the preceding "When passed two or more arguments, a new module created is." bit), and just doesn't come across as particularly natural.

Something more like "Creates a new {@link angular.Module} when passed more than one argument, or retrieves an existing {@link angular.Module} when only passed a single argument.", maybe? It's not perfect, but sounds slightly less weird to me.

If we're going to mention "name" at all, lets wrap it in codeblocks (surround with backticks) to hint that it refers to a parameter. And, if we aren't going to mention the position in the list, maybe at least refer to it as "the name argument" or something.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes i like that! How about:
"Passing one argument retrieves an existing {@link angular.Module}, whereas passing more than one argument creates a new {@link angular.Module}"

Copy link
Contributor

Choose a reason for hiding this comment

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

that sounds good to me! --- Minor nit, comma before "while" --- and you might consider replacing "while" with "whereas", but I'll leave that up to you

@caitp
Copy link
Contributor

caitp commented Aug 11, 2015

lgtm

@caitp caitp closed this in 1bd451d Aug 11, 2015
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants