Angular service word overloaded: rename one service and another SERVICE on angularjs.org API doc

[specialorange]

http://stackoverflow.com/questions/23940333/angular-service-word-overloaded-rename-one-service-and-another-service-on-angul

As with most, I am trying learn what differentiates the different service providers in angularjs, {service values, service factories, service services, and service providers}. You may have just read that as service services and thought I was the one who was crazy. I am not. Angular developers are the ones who are crazy, and they even notated it on the API on providers here, stating

Note: Yes, we have called one of our service recipes 'Service'. We regret this and know that we'll be somehow punished for our mis-deed. It's like we named one of our offspring 'Child'. Boy, that would mess with the teachers.

Well, their misdeed isn't clear enough. In some cases, I know which one they are talking about, usually because it is written grammatically singular service, but in many other cases, it is pluralized, and I don't know which service they are talking about, all services, or just service services.

I would like to propose that the API documentation differentiates these two terms by one being ALL CAPS, ie SERVICE or SERVICES and the other be service or services or if at the beginning of a sentence, Service, or Services. Hopefully you agree too. The problem is that I can't initiate a pull request to the API, as I don't know which words in the documentation are which. So I am in a predicament.

How do I get the clarification for the overloaded terms in the API? without asking them on SO for basically every sentence using the term service(s).

Also, per this suggestion, Instead I would consider clarifying every usage of the service() method to distinguish it from the general term service.

[RichardLitt]

As said in angular/angularjs.org#116, SERVICE isn't the best as it is more common. service() should work for the method well enough.

Good point, @specialorange.

[petebacondarwin]

+1 @RichardLitt

Anyone want to put together a PR with service() for references to the method?

[RichardLitt]

Looking closer at this, they are differentiated pretty regularly by calling the Service recipe with a capital. It's consistent across the other services, too. I'm not sure that changing it to service() would actually be more helpful than it currently is.

Can you point to a specific example where it should be reworded wether the text is referring to a Service or a service? Either way, we should just add a sentence clarifying this.

[specialorange]

It is confusing when the word is at the start of a sentence:

Services are objects whose API is defined by the developer writing the service.
Note: Service recipes follow a design pattern called constructor injection.

Here 'service' is both:

Let's say that our unicornLauncher service is so awesome ...
Let's say that our unicornLauncher service can stamp a unicorn with the

What is a provider and what is a service? Aren't Providers a special type of service [general service, not Service or Service() ]

During application bootstrap, before Angular goes off creating all services, it configures and instantiates all providers. We call this the configuration phase of the application life-cycle. During this phase services aren't accessible because they haven't been created yet.

I don't mind doing the PR once we come to an understanding of how to handle these.

[RichardLitt]

The first one is clear to me because Service.service hadn't been introduced yet. The second example is confusing, agreed.

The third and fourth are less confusing: they're referring to the parent Service, as they don't mention recipes. It doesn't make a difference semantically if you understand them as one or the other, I think.

And I'm lost as far as Providers being a type of service.

@btford you wrote the initial .ngdoc. Any word on this?

[thebigredgeek]

Could we not simply refer to them as injectables?

[petebacondarwin]

Providers are not services. Providers are responsible for creating services. They are injectable but only into other providers and config blocks. Providers are singleton objects (created by calling an injectable function) that must contain a property called $get(), which holds the factory function for the service. When the injector needs to construct a service, it finds the relevant provider and uses $get(), to get the service.

All services are created by providers but Angular kindly automatically generates these for us depending upon the module method we use:

• factory(factoryFn) - this is the simplest provider which looks like: { $get: factoryFn }
• value(val) - angular generates the factoryFn for us: { $get: function() { return val; } }
• service(Type) - angular generates a factoryFn that "instantiates" a new object using the Type as an "injectable" constructor: { $get: function($injector) { return $injector.instantiate(Type); }

I think injectables is a reasonable name for things that can be injected during normal application runtime: services (which can be defined by factory(), value(), service(), provider()) and constants; also components, which I often use to refer to all things Angular (services, filters, controllers, directives).