Updating stuff on the Wiki

[Iyanga]

Originally Posted by Cr4x I guess all of your were right. However, for "beginner" it is not immediately recognizable that Lua has the ":" operator which causes in this case the eventCode as first Argument. The list of parameter are correct, however it should be mentioned at the top of the EVENT site, that there will be always the eventCode as first argument.

myfunc(object, param1, param2)

That's the signature.

That LUA allows myfunc to be called in three ways, as:
obj.myfunc(otherobj, param1, param2)
obj.myfunc(obj, param1, param2)
obj:myfunc(param1, param2)

does not suddenly change the signature of myfunc.

The signature for string.len is string.len(string s).
It is not string.len(), just because you can use name:len() as shorthand for name.len(name). And I have never seen a documentation that pretends that string.len(string s) would be string.len(). And LUA documentation is obviously even older than WoW addon documentation.


You can easily see the difference if you take the opposite example and make a function
myfunc(param1, param2)

Calling this function with obj:myfunc(param1, param2) will not work and you would never call this function with obj.myfunc(obj, param1, param2), because you see immediately that it violates the signature.

[Cr4x]

Originally Posted by Iyanga myfunc(object, param1, param2) That's the signature. That LUA allows myfunc to be called in three ways, as: obj.myfunc(otherobj, param1, param2) obj.myfunc(obj, param1, param2) obj:myfunc(param1, param2) does not suddenly change the signature of myfunc.

I would say, it depends how it is declared.
because you should always document the declaration and not the "calls"

Originally Posted by Iyanga The signature for string.len is string.len(string s). It is not string.len(), just because you can use name:len() as shorthand for name.len(name). And I have never seen a documentation that pretends that string.len(string s) would be string.len(). And LUA documentation is obviously even older than WoW addon documentation.

http://lua-users.org/wiki/StringLibraryTutorial
Just an example

Originally Posted by Iyanga You can easily see the difference if you take the opposite example and make a function myfunc(param1, param2) Calling this function with obj:myfunc(param1, param2) will not work and you would never call this function with obj.myfunc(obj, param1, param2), because you see immediately that it violates the signature.

LOL sorry, but you are comparing apples with pears

So
Declaration: function MyObj.myfunc(self, param1,param2) end
Usage: MyObj.myfunc(MyObj, foo, bar)
or: MyObj:myfunc(foo,bar)

however >
Declaration: function MyObj:myfunc(param1, param2) end
Usage: MyObj.myfunc(MyObj, foo, bar)
or: MyObj:myfunc(foo,bar)

2 declarations using a different parameter list, but on the stack the functions are the same, 3 arguments, doesnt matter how they called.

In other languages you dont have to use such ":" operator, because a "this" reference to the object itselfs exists.

[Iyanga]

Originally Posted by Cr4x I would say, it depends how it is declared. because you should always document the declaration and not the "calls"

Right.

http://lua-users.org/wiki/StringLibraryTutorial Just an example

Exactly what I said:
string.len(s)
not string.len()

They gave the shorthand example if you have an instance of string named s, too.
s:len() (they didn't write string.len() for a reason..)

Declaration: function MyObj.myfunc(self, param1,param2) end Usage: MyObj.myfunc(MyObj, foo, bar) or: MyObj:myfunc(foo,bar) however > Declaration: function MyObj:myfunc(param1, param2) end Usage: MyObj.myfunc(MyObj, foo, bar) or: MyObj:myfunc(foo,bar) 2 declarations using a different parameter list, but on the stack the functions are the same, 3 arguments, doesnt matter how they called.

"The effect of the colon is to add an extra hidden parameter in a method definition and to add an extra argument in a method call. The colon is only a syntactic facility""

MyObj:myfunc(param1, param2)
IS the definition of myfunc(MyObj, param1, param2)

Even the LUA documentation you linked agrees with me that it is part of the argument. How can it NOT be part of the argument list if you can access it as argument...?

[Stormknight]

Here's a simpler real world example of a restaurant menu.

At the top, "Every order comes with fries"

In the documentation below, of every meal they sell, there is no mention of fries.

There doesn't need to be, as they said above that every order comes with fries.


For the lua code though, it's not even that people are being lazy and don't want to write fries many times.

The event THIS_EVENT returns parameters (string mytext)

The event handler, which is used to interact with the event, returns the object reference PLUS whatever is returned by the event itself.

Documenting the events as returning the object would be incorrect.

Edit: this is feeling a bit silly now, so is my last post on the subject.

[Seerah]

/sigh...

RegisterForEvent is a method defined to the EVENT_MANAGER object. It takes three parameters, the unique identifier for the addon that wants to watch for the event, the event code to watch for, and the function to call when the event fires.

(Optionally, the metatable for CreateControl also adds the RegisterForEvent method to the userdata table of controls that are created. So you could also do MyFrame:RegisterForEvent(eventCode, function) instead of going through EVENT_MANAGER.)

The RegisterForEvent method on EVENT_MANAGER works like this.

Addon A wants me to watch for event B and call function C when event B fires.
Event B fired! I will now send confirmation to Addon A that it was event B that fired, along with all returns from event B that the addon would be looking for.
eventFired = eventCodeB
eventReturns = ...
functionC(eventFired, ...)

The reason WHY the event handler (RegisterForEvent) passes along the event code is this:

Addon A wants me to watch for event B and call function C when event B fires.
Addon A wants me to watch for event D and call function C when event D fires.
Addon A wants me to watch for event E and call function C when event E fires.
Event D fired! I will now send confirmation to Addon A that it was event D that fired, along with all returns from event D that the addon would be looking for.
eventFired = eventCodeD
eventReturns = ...
functionC(eventFired, ...)

This does not make the eventCode part of the the returns list for the event. The event handler takes the event code and prepends it on to the list of returns from the event before sending that along to the function.

[Iyanga]

Originally Posted by Seerah The RegisterForEvent method on EVENT_MANAGER works like this. Addon A wants me to watch for event B and call function C when event B fires. Event B fired! I will now send confirmation to Addon A that it was event B that fired, along with all returns from event B that the addon would be looking for. eventFired = eventCodeB eventReturns = ... functionC(eventFired, ...)

That's what I've written exactly before:

function obj.myfunc(param1, param2)
return obj.myfunc2(param3, param1, param2)
end

Including the fact that it doesn't matter how param3 makes it way into the argument list - it is there.

The reason WHY the event handler (RegisterForEvent) passes along the event code is this:

So you can have the same function as handler for different events. It's pretty easy without a large example.

This does not make the eventCode part of the the returns list for the event.

Of course it does. Who else does decide which arguments an callback gets, if not the event handler? I'm not the one deciding it, when I'm registering the handler obviously, I can't tell the event handler what I want. So the event handler does decide it. So the event code is no different than every other parameter. And the description how a callback function for an event has to look like must (for me obviously) equal the way the event handler _does_ call the function.

The event handler takes the event code and prepends it on to the list of returns from the event before sending that along to the function.

So the event code is part of the arguments for the function that is called and previously registered. What I said. The event handler might also decide to remove or nil arguments.


I guess we have to agree to disagree.

[thelegendaryof]

I agree that the discussion becomes a bit like running in circles.

As a conclusion I would just put an basic explanation of how those work as an introduction to Events including an example like this:

Originally Posted by Cr4x So --Declaration: function MyObj.myfunc(self, param1,param2) end --Usage: MyObj.myfunc(MyObj, foo, bar) --or: MyObj:myfunc(foo,bar) however > --Declaration: function MyObj:myfunc(param1, param2) end --Usage: MyObj.myfunc(MyObj, foo, bar) --or: MyObj:myfunc(foo,bar) 2 declarations using a different parameter list, but on the stack the functions are the same, 3 arguments, doesnt matter how they called. In other languages you dont have to use such ":" operator, because a "this" reference to the object itselfs exists.

The rest should stay like it is as it 's correct. However the Events itself need more documentation as to when to use them or how often they fire, when they fire or what values the parameters accept. That 's more important I guess.

Back to the topic, yes the Wiki needs updates badly. I'll try to help if I find time to do so and feel like my knowdlege is good enought for it to be documented. Oh, am I blind? Wasn't there a rule or help page how to properly update the Wiki (not as in how to use a Wiki by itself more like general guidelines or rules)? I guess that would help as well!

Anyway I'll go by the principle that more info is better info. If it 's incorrect feel free to edit it later on (even thought as I said I'll try to keep it quality stuff only there 's always something you could do better or more easily or just different). That 's fine right?

Edit:

@Stormknight: I really like the way how you documented EVENT_ADD_ON_LOADED! That 's actually a good template to start of. :3

Edit 2:

Hm, however wouldn't it be better to go for a general rule to use the best performance as possible for those examples? Meaning defining them as a local function instead of pushing them into a global object? Just speaking from an optimal point of view. See here:

http://stackoverflow.com/questions/6...level-function

Hm, I need to write some tests for this later myself and see how they perform. Especially since localized functions and variables can be a nightmare if you don't keep your code structured and know what you're doing. Globalized ones might be better after all.

[Seerah]

Yes, examples on the wiki should be the best example possible. However, having a global variable is better than having no example. But if anyone wants to improve examples, they may - it's a wiki!