[jQuery] jQuery API discussion
<html><head><style type="text/css"><!-- DIV {margin:0px;} --></style></head><body><div style="font-family:lucida console, sans-serif;font-size:10pt"><DIV>I think that there is space for improvement on both sides of API architecture and its documentation.</DIV>
<DIV> </DIV>
<DIV>We all like jQuery for how it looks like. We like its chainability, we like its alchemy. So we must preserve what we like most as much as possible, and doing so we'll also get to an evolution as opposed to a revolution. </DIV>
<DIV> </DIV>
<DIV>Sorry for my pomposity.</DIV>
<DIV> </DIV>
<DIV> </DIV>
<DIV>API architecture</DIV>
<DIV>-----------------</DIV>
<DIV>I'll leave this entirely in your hands, because my undestanding still needs to deepen more. </DIV>
<DIV> </DIV>
<DIV>Just one advice and one idea. Here goes the advice. People like to do things their way. So two ways of doing something, are always better than one. On this principle is based the most widespread software nowadays.</DIV>
<DIV> </DIV>
<DIV>And here goes the idea. I noticed many posts in this thread about the events issue. I think that bind, undind and trigger, when specialized over a click event, for example, could all three be synthesized in only one function called click. I like overloading even if I know it adds mystery. Correctly used also helps keeping tidy. </DIV>
<DIV> </DIV>
<DIV>bind: click(function...)</DIV>
<DIV>trigger: click()</DIV>
<DIV>unbind: click(null)</DIV>
<DIV> </DIV>
<DIV>This should be pretty clear to any programmer: unbind is like binding to nothing. If null cannot be used, any similar replacement will work: nothing, "", 0, undefined, {}; just choose (or make) one that fits.<BR></DIV>
<DIV>Then there is the difference between one shot and burst mode. This could be coped with by adding an optional boolean (or enum) argument. </DIV>
<DIV> </DIV>
<DIV>This way a 6 functions will be compressed into only one name. wow</DIV>
<DIV> </DIV>
<DIV> </DIV>
<DIV>API documentation</DIV>
<DIV>------------------</DIV>
<DIV>There is an official documentation that comes right from the source with an XML to HTML clockwork. I'll speak about this one. </DIV>
<DIV> </DIV>
<DIV>
<DIV>Functionalities must be differentiated from functions.</DIV>
<DIV>Functionalities need a unique id number.</DIV>
<DIV>Functionalities need their own filecard.</DIV>
<DIV>Functionalities need not be spread among many filecards.</DIV>
<DIV>Pseudo-Signatures can be augmented to represent optional arguments and their default values.</DIV>
<DIV>Filecards must cross reference each other on an "as needed" basis, but also on a more regular basis, like a section for referencing similar functionalities, or a reference to the group of their common function name.</DIV>
<DIV>Keywords must be added to functionalities and "deprecated" should be a keyword.</DIV>
<DIV>Documentation must be made available through browsing, references, keywords, categories and searches.</DIV></DIV>
<DIV>Examples must be improved on many levels. (see my third post in my blog)</DIV>
<DIV> </DIV>
<DIV>Here is something that goes towards what I mean: <A href="http://www.mondotondo.com/aercolino/jquery/docs/API/jquery-api2.xml">http://www.mondotondo.com/aercolino/jquery/docs/API/jquery-api2.xml</A></DIV>
<DIV>I only wrote again the documentation of the items with a number, whereas items with a # are original content.</DIV>
<DIV> </DIV>
<DIV>And there are three posts in my blog with all the ideas and details: </DIV>
<DIV>1: <A href="http://www.mondotondo.com/aercolino/noteslog/?p=42">http://www.mondotondo.com/aercolino/noteslog/?p=42</A></DIV>
<DIV>2: <A href="http://www.mondotondo.com/aercolino/noteslog/?p=62">http://www.mondotondo.com/aercolino/noteslog/?p=62</A></DIV>
<DIV>3: <A href="http://www.mondotondo.com/aercolino/noteslog/?p=65">http://www.mondotondo.com/aercolino/noteslog/?p=65</A></DIV>
<DIV> </DIV>
<DIV> </DIV></div>
</body></html>_______________________________________________
jQuery mailing list
discuss@jquery.com
http://jquery.com/discuss/