Talk: API Function articles/Preload

I removed the {{clr}} added by Socrates200X(talk • contr). 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)

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.

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)

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:

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:

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.

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.