Thankyou Andrew for working on this - it is sorely needed.
Some points I think we need voting/consensus on:
Agreed, this needs further discussion and clarification, but I feel it's one of the most important changes.
"be spread across multiple lines for complex types (including all objects and arrays, no matter how simple"
I don't see this as a major sticker - since we minify all code going out now, there's no reason not to and it means that we can get the full blame history much more easily.
We could be more specific about which yuidoc tags are required (Where is @namespace required?)
That's a hard one - I don't think that we should duplicate the entire yuidoc syntax guide here but perhaps once we get these docs ratified and start to generate real YUIDoc, we will have more of an idea. @namespace isn't required at all, but it is useful in modules with submodules primarily.
with a maximum length of 150
Okay, that can probably be dropped... but we should make the value in our .jshintrc match the value we wish this to be (180 chars is the figure mentioned in the standard style IIRC)
"In the case of object property assignation, there should be a space after the colon, but not before."
Property assignation is not really the same as an operator so I feel that these should be separate rules. Most JSON resources out there follow this standard -- see http://www.freeformatter.com/json-formatter.html#ad-output for example. Unless we have good reason, why should we break from this? It's also the format described by the RFC: http://www.ietf.org/rfc/rfc4627.txt (Section 8). Additionally, when writing in natural language, you don't write:
E-mail : email@example.com
You write it as:
Some instructions on how to use YUIdoc / shifter to check the format of the JS/comments would be welcomed.
There is already documentation on how to use Shifter, and YUIDoc. We could admittedly do with more. If others wish to contribute, I'd very happy to have help there ;)