Help talk:API Function articles/Preload

I removed the added by. Having something that extends over a horizontal separator line is quite common all over the wiki; yes, that area of the screen may become slightly less aesthetically pleasing, but the huge unmotivated gap in the rest of the page is quite a bit worse -- at least, in my opinion. -- Mikk (T) 11:34, 16 October 2006 (EDT)


 * Giant gaps = not good in my book. It's a minor aesethic thing, tbh. -- Kirkburn  (talk) 13:00, 16 October 2006 (EDT)

I'm going to replace the code snippet below the one-line definition to use the Code/Begin and Code/End templates instead of the standard one-space code block. This is so the code box isn't drawn all the way across the screen in some skins, which runs into the WoW nav panel.

Socrates200X 21:11, 16 October 2006 (EDT)


 * That makes it harder for newcomers to edit though. My plan was to wait until Rustak fixes CSS access for admins and then I was going to fix the stretch issue in all skins.  -- Mikk  (T) 21:15, 16 October 2006 (EDT)


 * Then again, Code/Begin:d stuff wraps properly if it becomes too long. And it isn't that bloody hard to edit when the tags are already in place.  -- Mikk  (T) 21:17, 16 October 2006 (EDT)

Remove Parameters header
I'm wondering why "arguments" and "returns" are listed under "parameters" and do not have their separate sections. In my opinion "parameters" is just another word for "arguments". "returns" has nothing to do with these. All the pages I know of do it that way, why do we do it otherwise? What's the reason for that? Since I don't see any reason for keeping "Parameters" the page has been changed, parameters erased and Arguments as well as Returns are now level 2 headers. Here are just some examples on some common API pages: --Luke1410 11:23, 12 April 2007 (EDT)
 * http://msdn2.microsoft.com/en-us/library/ms724408.aspx
 * http://java.sun.com/javase/6/docs/api/java/security/Identity.html#toString(boolean)
 * http://www.php.net/manual/en/function.ftp-alloc.php

Remove repeated list of arguments/return value
Sticking with the current boilerplate means that arguments and return values should be listed twice. Once in a single line (comma separated) and right below that line in a list. This seems to be unnecessary, does not serve any purpose and looks quite weird for functions with only a single argument and/or return value. Therefore those redundant lists have been removed. --Luke1410 13:07, 12 April 2007 (EDT)


 * Granted, I've been deleting the lines myself for functions with only single arguments / returns, but imo it helps clarity for more complex ones. It definitely helps to have them for functions with multiple types of return values / argument lists, where you to document the different types of calls / returns in the Arguments/Returns sections rather than clutter the synopsis unnecessarily. Mikk  (T) 10:04, 14 April 2007 (EDT)


 * You are right. In those cases the current layout is not clear enough and might be confusing. But I don't think that this additional line is the best way to clarify things.
 * API_GetItemInfo is an example for a function which takes multiple values as its argument. By just looking at the list (without the additional line) one gets the impression that the function accepts 4 arguments. Only by reading the line: "(itemId or "itemString" or itemName or "itemLink")" it is made clear that the function only accepts one argument.
 * But that could also be done by changing the layout for the arguments/return lists.
 * As an example for API_GetItemInfo the argumentlist could look like this:


 * === Arguments ===
 * item - The specific item in one of the following formats:
 * itemId : Integer - The numeric ID of the item. ie. 12345
 * "itemString" : String - The full item ID in string format, e.g. "item:12345:0:0:0".
 * itemName : String - The Name of the Item, ex: "Hearthstone" (the item must be equiped or in your Inventory for this to work).
 * "itemLink" : String - The itemLink, when Shift-Clicking items.
 * --Luke1410 18:57, 14 April 2007 (EDT)


 * Just thought a bit more about that suggestion and though it works fine for a constant number of return values / parameters, it does not work in case the number of those is variable (i.e. the function accepts optional parameters).
 * So here comes another suggestion using EBNF to describe the function's syntax.
 * Single line description about what the function does.
 * === Syntax ===
 * === Arguments ===
 * as in the current boilerplate without a descriptive first line
 * --Luke1410 09:02, 15 April 2007 (EDT)
 * --Luke1410 09:02, 15 April 2007 (EDT)


 * Well, we're already doing optional parameters like that, but what I was thinking of was more along the lines of functions accepting totally different parameters depending on type:
 * Texture:SetTexture("texturePath")
 * Texture:SetTexture(r, g, b[, a])
 * Texture:SetTexCoord(minX, maxX, minY, maxY)
 * Texture:SetTexCoord(ULx, ULy, LLx, LLy, URx, URy, LRx, LRy)
 * Mikk (T) 06:35, 18 April 2007 (EDT)


 * That would be quite the same. For instance:
 * === Syntax ===
 * === Arguments ===
 * texturePath : String - description
 * r : number - red
 * g : number - green
 * b : number - blue
 * a : number - alpha
 * --Luke1410 18:28, 18 April 2007 (EDT)
 * --Luke1410 18:28, 18 April 2007 (EDT)


 * I believe it should be in exactly that way how Mikk  wrote it:
 * === Syntax ===
 * === Arguments ===
 * This is how they usually write Perl documentation, and I like it. At least it makes perfect sense for us, humans; and does not clutter with unnecessary logical operators which sometimes may be hard to follow. I would also like to argue that writing "texturePath" just to indicate that it is a string is absolutely unnecessary. Because why don't you then indicate booleans/numbers/tables/etc? It is already mentioned in arguments description that texturePath is a string, and that should suffice in my opinion.
 * Now, as for GetItemInfo here's my version:
 * This is how they usually write Perl documentation, and I like it. At least it makes perfect sense for us, humans; and does not clutter with unnecessary logical operators which sometimes may be hard to follow. I would also like to argue that writing "texturePath" just to indicate that it is a string is absolutely unnecessary. Because why don't you then indicate booleans/numbers/tables/etc? It is already mentioned in arguments description that texturePath is a string, and that should suffice in my opinion.
 * Now, as for GetItemInfo here's my version:

itemName, itemLink, itemRarity, itemLevel, itemMinLevel, itemType, itemSubType, itemStackCount, itemEquipLoc, itemTexture = = GetItemInfo(itemID) = GetItemInfo(itemString) = GetItemInfo(itemName) = GetItemInfo(itemLink)
 * I know it looks a little bit funny, but readability on the first place
 * -- Fibby 00:56, 20 September 2007 (UTC)