Improve type & parameters display in method signature

[nene]

From Peter deHaan:

Odd, I just noticed this and don't believe I've mentioned it before, but why does a method signature list {datatype} argument instead of argument : {datatype} (similar to the parameters list? Or is that just a standard JSDoc thing?

changeListener( Object operation, Object eventName, Object fn, Object scope, Object options, Object order )

    operation : Object
    eventName : Object
    fn : Object
    scope : Object
    options : Object
    order : Object

Why isn't it something like:

    changeListener( operation : Object, eventName : Object, fn : Object, scope : Object, options : Object, order : Object )

[nene]

A fair concern.

This is so purely for historical reasons - that's how the old ext-doc output looked.

I think the ordering in method signature comes from the fact that this is how parameter types are placed in most C-based languages. See JavaDoc for example:

http://docs.oracle.com/javase/6/docs/api/java/util/logging/Logger.html#entering(java.lang.String,%20java.lang.String,%20java.lang.Object)

Looking at other JavaScript documentations I see that usually the type information isn't shown in method signature at all:

http://api.jquery.com/toggleClass/ http://yuilibrary.com/yui/docs/api/classes/Model.html#method_validate http://api.prototypejs.org/language/Hash/prototype/each/ http://mootools.net/docs/core/Types/Array#Array:each https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/Reduce

The only exception I found is Google, but their documentation is in quite different format anyway, and doesn't describe the parameters separately at all, so the method signature is the only place where both the parameter names and types are listed:

https://developers.google.com/maps/documentation/javascript/reference#Marker

So one idea is to remove the types from the method signature completely. But in all those other docs you don't have to expand the method to see all of its description - so having the types in signature might be justified in our case.

I doubt if simply swapping the parameter type and name around and adding a semicolon would add any benefit - IMHO it would just make the method signature even longer. But we could experiment with removing the parameter types from the signature completely - this could make the docs look much cleaner, e.g. here the long type definitions are obscuring the actual three simple parameter names:

http://docs.sencha.com/ext-js/4-1/#!/api/Ext.Template-method-insertAfter

[nene]

Fixed in 2693008d6990273f32f56c7816516283414230c1