Jörn Zaefferer schrieb: > Hi jQueryians, > > as discussed before, the jQuery API contains quite a lot of methods. The > event shortcuts or one thing, another is single methods with optional > parameters. Let's take slideDown() as an example. It has two paremters, speed > and callback. There is one method documented with only speed as a paremter, > and one with both. > > While it would be easy to merge the docs for these two, eg. add the example > and slightly modify the text, there should be a useful mechanism to mark > parameters as optional. > > Some ideas: > @param Object speed (optional) A string repres.. > @param [Object speed] A string repres.. > @param Object (speed) A string repres.. > > The docs parser could parse this format, add an attribute to the json/xml > file and the API stylesheets could then format the docs. > > This should be only applied where applicable, like slideUp() etc., not to $(). > > There are other cases where a single methods accepts different types of a > argument, like add() accepts a String, a Element or an Array of Elements. It > actually does always the same, no matter what the argument is, only the > actually executed code is somewhat different, but nothing a user has to worry > about. > > The good thing: Possible resulting changes affect only the documentation, no > code at all! > > Your opinions please!
Hi Jörn, I found another little glitch with "&" characters in inline documentation. Unless you do not escape it as "&" the XML for the generated docs is ill-formed. But that means, that the inline documentatin is misleading, for example for the form plugin formSerialize method: "This method will return a string in the format: name1=value1&name2=value2" which should apparently read: "This method will return a string in the format: name1=value1&name2=value2" -- Klaus _______________________________________________ jQuery mailing list discuss@jquery.com http://jquery.com/discuss/
