3 ms·
Never mind all this nonsense about blogs and voting and such. Rewrite the docs. From scratch. They are dreadful. I would like to help but every time I think I
by jacques_chester 13y ago
Never mind all this nonsense about blogs and voting and such.
Rewrite the docs. From scratch. They are dreadful.
I would like to help but every time I think I have understood angular, it turns out that no, I didn't. There was an undocumented feature that's well documented ... if you read the source code and have been subscribed to the mailing list for a year.
It would also be nice to have a consistent naming standard. For example, why do these two functions have inconsistent parameter names:
$watch( watchExpression, listener, objectEquality )
$watchCollection( obj, listener )
The purpose of `watchExpression` and `obj` is the same: they are an expression that evaluates to the thing that is watched for changes. It just seems unnecessarily messy. PHP-standard-libs messy.
And then there's the confusing use of names. `objectEquality`? No: it's not a function that you pass in. It's a flag to watch-by-value instead of watch-by-reference. Why not call it `watchByValue` instead?
- acjohnson55 13y agoThank you! Unfortunately, poor documentation seems to be the fashion for JS projects. You're lucky if you get full parameter descriptions and return types for API functions. And the same for expected callback functions? Forgetaboutit. Just because the language is dynamic doesn't mean APIs should be haphazardly documented.
- dustingetz 13y ago"if you read the source code and have been subscribed to the mailing list for a year" Not only do I read the source and daily newsgroup digests to my preferred javascript stack, I read the source and newsgroups of the other popular choices. If I didn't know all the answers, i wouldn't be a very good tech lead, would I? The ecosystem is moving at high velocity and that is a good thing.
- jacques_chester 13y agoI feel blamed for relying on the docs, it made me angry. The first version of this comment made a snarky reply. I've actually become quite familiar with some parts of the Angular source. It's the only way I can make sense of the documentation. This is not my dayjob. I am doing this because I recognise that front-end is one of my two biggest weaknesses. Right now I am making forward movement by headbutting. It seems unnecessarily like self-flagellation.