Talk:JSAPI Reference
From MDC
Contents |
[edit] Progress status
All functions from the old documentation were imported, and many inconsistencies were fixed along the way.
The data structures of the old documentation were also migrated and sanitized against inconsistencies.
Some macros seem to have been imported, they all need to be revised, and the missing ones should be added.
Currently, there are broken reference links in many articles, and most of them are using a plain first-level link such as:
[[JS_XXX]]
instead of:
[[JSAPI:JS_XXX]]
Moreover, some of the first articles migrated here from the old documentation are using another link scheme. These links should be fixed, possibly by an administrator who might have proper tools to handle such massive relinking. This is a daunting task considering that each article has a "See also" links section.
In any case, when adding new articles, one should ensure to observe the style of currently existing entries in the new documentation for consistency. Using an existing function's source to create a base template might be a good idea when documenting new functions. A pedantic approach is usually helful for reference documentation writing.
- I've visited all the pages and cut down the style quite a bit. Copying an existing page still helps though. Similar or related functions should appear on the same page instead of separate ones. Names of JSAPI features should usually be links. —jorendorff 06:39, 23 April 2008 (PDT)
[edit] Functions list order
It would probably be nice to also eventually have a list of functions by topic, i.e. Functions to work on contexts together, ones to work on strings as a group etc... Although the "See also" references for each article might do just that provided they're properly updated. --mmondor 08:31, 18 Aug 2005 (PDT)
- JSAPI Reference is now grouped by topic. It's a lot more helpful that way. "See Also" has been removed from a lot of pages in favor of wiki links in the text. —jorendorff 06:39, 23 April 2008 (PDT)
[edit] Reference section duplication among common topic articles
If we were to rely on "See also" sections to replace a per-topic index, it would almost be desireable to define templates/macros or such for each major function group, so that they could dynamically be updated in each string related article whenever a new string function is added, for instance. As it currently is, there is great duplication in the reference section of the articles. Perhaps that another way to handle this would be using some sort of iframe. Of course, even if such a system was used to minimize duplication of say, string functions, if a particular string function requires reference to arbitrary other functions not within the template, this would need to also be possible.
Comments appreciated, --mmondor 08:31, 18 Aug 2005 (PDT)
- They should have templates. Not something I'm working on, though. —jorendorff 06:39, 23 April 2008 (PDT)
[edit] Other JSAPI functions to document
I added all missing functions/macros from the SpiderMonkey 1.6 public API directly to the main list, so that it'll be easier for me to fill them in afterwards. This however will be filled as time permits. Some of those used to be listed here, but I see no point in isolating/hiding undocumented public functions. Other people may immediately see that their documentation is missing and also fill the gaps occasionally this way. mmondor 14:59, 25 July 2007 (PDT)
- There are still many undocumented functions. SpiderMonkey 1.8 will be released soon; it includes many more APIs no one has bothered to document. —jorendorff 06:39, 23 April 2008 (PDT)
[edit] Short and Long style links
Since the short and long formats are being switched quite often, I'll attempt to link them shortly for now and to focus on adding articles which properly link to eachother. Because there currently are articles of both styles, some of which with a redirection link, I believe that it'll be best to revise them all and link them properly with long names after all functions are imported... --mmondor 08:56, 8 Aug 2005 (PDT)
- MMondor: yah, don't worry about this too much right now. Moving the content around once it's in the wiki is relatively straighforward, it just requires an admin to do page deletes and such. Just keep doing what you're doing, and we'll worry about moving stuff around later. Thanks :) --- dria 09:54, 8 Aug 2005 (PDT)
- They all now use short names, like jsdouble. —jorendorff 06:39, 23 April 2008 (PDT)
[edit] Deprecated elements to be revised
Someone with proper authority should revise the list of deprecated elements. Currently deprecated elements were also deprecated in the old documentation.
[edit] Blackboard: Users' discussion board
1. I think a Template would be useful for relinking all entries. Although, why do we need to change the links scheme anyway? It'd be easier to use Categories instead (in a way JSAPI versions could evolve, and old and new stuff coexist. -- Manuel 19:55 -05:00, Oct 1st, 2005.
- Unless categories can do stuff I don't know about, they aren't sufficient for this. Wikipedia widely uses templates for this kind of thing. —jorendorff 06:39, 23 April 2008 (PDT)