I really really want to try loving AngularJS, and to some extent i really do -- but when I need to look at the documentation, I feel like shedding tears.
Angular-team: You have an awesome product. Please fix your documentation, and include examples usable with angular-seed, instead of the standalone-examples.
Documentation got waaay better these last weeks. Hope that continue.
About examples, we can't point enough the awesome work of the Angular-ui team. I think their code is near the state of the art of Angular. But yep, a big complete applications using Angular in which we can digg into would be nice.
In my experience, Code Scalings THE problem you got with your real world application. Restangular helps. A lot.
Services are not that useful, Factories even less (but when they are, it's a neat feature), and Providers are simply something internal that we can optionally use if we want do some meta-meta-programming (factories do the first meta).
I hope the guideline for the next release will be to get rid of the over-engineering that makes everything complex when you need to do something UI-dynamic (ever try to attach dynamically a tooltip ?).
Sometimes Angular just go on your way and don't want to move.
The things I would want to be changed:
- Remove Providers. that's just redundant with factories, with the only exception as some complex internals we shouldn't use anyway
- Remove $rootScope. It's an internal thing that should not be used.
- Make $q better. It's a pain to use. Really.
- Better control to digests (monitoring, postponing mostly)
- Angular binding with CSS would be awesome. But it needs some work to make a clean separation.
- Directives. Seriously: the way to declare them really should be changed. Returning this starnge object, what the point ? What about Directives Factories for all the multiple ways to declare them, and in last resort only, using the weird object when you need that fine grained control. Mixing all together like the current state is not viable.
Could you explain a bit more about the tooltip issue you've mentioned? I'd be interested to explore to understand what the limitation is and how I (or others) might approach it.
I'm not sure I agree with all of your comments.
I find that services are relatively essential building blocks for my applications.
Providers are there so that you can preconfigure your modules. It's a legitimate use case. Take Restangular, for example - it's so useful to you because it's a provider that you can configure for your app.
I can see how $rootScope could be perceived as code smell but after examining how angular uses it internally I'm ok with the way I use it.
Directives are confusing the first time you see them. You need to see a few examples. Though I don't think there's a problem with the api for declaring them. There's a lot to configure - it's mostly optional, but you may well need all of it eventually.
Angular gives you a framework to build on. You can create really amazing components that are totally reusable on your other projects. Sometimes they come in the form of directives, sometimes they're other types of module. Often when you start abstracting that out you'll need to get a bit closer to the metal. Angular provides an api for you to work with in those cases and it's ok to take advantage of that.
> Could you explain a bit more about the tooltip issue you've mentioned?
Say that you have a dynamically generated form where an input should display a tooltip only in specific cases.
Using tooltip="" will not do the trick, you have to do some sorcery to attach dynamically your tooltip, aKa: using compiler in your controller to replace dynamically the DOM region with the DOM elements returned by $compile and jQuery.
> I find that services are relatively essential building blocks for my applications.
But they doesn't help much against the issue of feature scaling.
Some UI logic just can't be factorized. Some other data handling is to specific to be re-used elsewhere. In a large business application, logic is poor but corner cases are legion. We made the choice to keep our specific logic near the place they are used against using services because that doesn't add any value.
> Providers are there so that you can preconfigure your modules
Again, thats what the rest of the world call 'a factory'. You can perfectly imagine a Factory that register in $injector it's instances. IY think Provider should stay something internal and not be documented as a feature everyone can use. It's not.
> I can see how $rootScope could be perceived as code smell but after examining how angular uses it internally I'm ok with the way I use it.
I am too. But I don't want anyone else than hackers to use it.
> Directives are confusing the first time you see them.
They are confusing because everything is blend together. Separate the different use cases and everything will be simpler. Even if it's the same internal thing (that you can use directly if you need).
My point is that if you provide different handlers, noone will ever fear the directives.
> You can create really amazing components that are totally reusable on your other projects.
If only...
In the real world, there is no way my current employer will accept I'll reuse his code for my next project. Only FLOSS libraries can do that.
Its an essential tool for all kinda of hackery which maybe is not the best ways to do things but its the fast way.
I ran into a jqeury popup bug and there was no way to get data inside it without crowbaring the rootScope. For some weird reason it would not accept a controller within, or decorating the popup, depending on where the popup HTML was placed within the HTML file.
Note: I never worked out it was a bug or me not understanding jquery properly. The point is $rootScope can allow corners to be cut in emergency situations.
You are right. It can be hackly usefull. I suggest to expose it only the internal way: via the ctrl.$get array so that you have to know what you are doing.
- Services, factories, constants, values ... they're all just syntactic sugar on top of provider, so that's not really something you just rip out. You just don't use it if you don't need to. And you very rarely do.
- What's problematic with $q, compared to any other promises implementation?
- The future of directives has to be as HTML5 web components, though how that'll happen, I have no idea!
The documentation isn't great but it isn't terrible either. I hope people thinking of giving angular a try aren't put off by the constant over-dramatisation.
Maybe it's because improving the doc has not too much benefit for the contributor because he/she already understands the badly documented problem. But improving code has instant benefit for the contributor because he probably fixing something he still using.
I think the simpler answer is that most people who complain about documentation cannot improve the docs because they don't know how. If they did understand what was being explained in the documentation, they wouldn't be complaining in the first place.
I was trying to make the distinction between those who get to the level of competence of contributing vs those who don't reach that point. The former group being people who don't complain about the docs (or at least not as loudly) while the latter group does. But I guess I didn't get that across clearly, sorry.
This is why my projects have always been willing to cut a deal with newbies to exchange stupid question credits for doc patches - i.e. "if you feel X is underdocumented, the core team will happily give you a personal tour of X provided you write up the results for the next guy to read" - which tends to help the incentive problem.
I do love and use AngularJS, but finding solutions to problems I have with it seriously the most frustrating experience I've had with any language. It can be a real pain going from Ruby on Rails development, for which there is always a gem or a couple-line fix for a given problem, to AngularJS. Sometimes I find a solution by cobbling together StackOverflow answers, sometimes random Google Groups posts and JS fiddles, but I never find the answer in the AngularJS docs. I use the official documentation only as a reference when I already know what I'm doing and only forgot the name of some property.
I'm currently working on a project with Angular right now updating a current product largely built on Backbone to Angular.
Overall I'm super impressed with it, when you know what to do its almost like magic. Callbacks, events? What are those? But like others in this thread - I wish the documentation was better - atleast with examples on more of the doc pages. It has been improving however.
I can't believe Blogger still does not change this redesign. It lags when I scroll text. It has this silly layout dropdown. The top bar obscures content. Why.
I've been deep in the docs for the past couple months, and I have never found them to be inaccurate. A bit sparse sometimes, but on the other hand the source code is very well commented. Between the two you can find your way without too much effort.
There are two kinds of developers... those who want a single framework that will solve all their problems and which they never have to look into... and those who like to understand one or more abstraction levels below where they're actually working.
Digging into a framework's source code is natural to the latter group, but utterly alien to the former.
Documentation written for the latter group describes mechanisms, design principles, APIs, etc. The former group instead requires examples and step by step tutorials.
Both will call documentation terrible if it doesn't conform to their expectations.
You described that nicely. I didn't realize there was such a split, but I'm definitely of the former group. Ugh, I just want to write my own cool stuff and understand it. If I wanted to write and understand the inner workings of AngularJS, that's what I'd be doing.
Until you need to do something with WebGL and you realize you have no idea how to write fast code because you're more than a dozen abstraction layers removed from the silicon.
Angular-team: You have an awesome product. Please fix your documentation, and include examples usable with angular-seed, instead of the standalone-examples.
Has the documentation improved with 1.2?