Types page does not explain how named functions can be passed

[Chealer]

According to http://api.jquery.com/Types/ "this page documents virtual types like Selectors, enhanced pseudo-types like Events and all and everything you wanted to know about Functions. "

http://api.jquery.com/Types/#Function mentions that "A function in JavaScript can be either named or anonymous." and provides examples of declarations:
function named() {}
var handler = function() {}

There is however not a word or example about passing named functions, which is supported by numerous jQuery functions such as .change(). The following discussion explains:
http://stackoverflow.com/questions/7963609/how-can-i-name-and-call-a-jquery-function

Note that there is no explanation there of how to read the description of functions which take Function arguments. For example, https://api.jquery.com/change/ says:
handler
Type: Function( Event eventObject )

What "Function( foo bar )" means should be specified somewhere.

This was originally reported as jquery/jquery#2704
Credits to timmywill for pointing me to the right ITS.

[mgol]

provides examples of declarations:
function named() {}
var handler = function() {}

IMO these examples are confusing as the fact that the first function is named and the second anonymous is not the only difference; the first one is a function declaration and the second creating a new variable to which a function expression is assigned. It'd be better to have:

var namedHandler = function named() {};
var anonymousHandler = function() {};

Using named functions is not so much supported by jQuery as by JavaScript itself; named functions work mostly the same as anonymous except that they have a name you can reference inside them.

Perhaps we could have an example with a named function, though. Using such functions in callbacks is discouraged if you need to support IE<9 as they have serious bug in handling them but otherwise you're fine.

[dmethvin]

I think this is more about our syntax for documenting functions that are passed as arguments to API calls, and not about JavaScript notions of named or unnamed functions?

@Chealer you mentioned the .change() API, here's one of those signatures:

.change( handler )
handler
Type: Function( Event eventObject )
A function to execute each time the event is triggered.

So your question is about the "Function( Event eventObject )" part? It just means the handler argument is a JavaScript function (of some kind) that receives one argument, the eventObject.

Is that what you're asking about? Can you clarify what it is that you would like to see added?

[Chealer]

mzgol, do not expect guidance from me, I am inexperienced with JavaScript.

It is perhaps a good idea to add the form var namedHandler = function named() {};. But I am less sure it is a good idea to remove the form function named() {}. I am fine with whatever is decided, as long as the page explains how to pass the function defined by each declaration.

dmethvin, I mentioned the problem you are referring to, but the real scope of this ticket is just to explain how named functions can be passed. Documenting how to read functions which allow Function arguments is just bonus points. If passing named functions is documented, please close this ticket, and if the secondary issue remains, I will decide if I open a new ticket to properly report it.

What I would like to see added is a description of the arguments with a synopsis Function([Type varName [...]]) indicating that such an argument refers to a function which will receive an argument of type Type. By the way, if the manual pages do not define the contents of varName, then it is useless to name it. In this case, the description could just read Function( Event ).

[dmethvin]

Not sure that I understand...named functions are just passed by their names. Wherever they are declared they may (or may not) declare the arguments that are passed when the function is called. Since this is the jQuery API docs there's only so much we should be doing to explain basic JavaScript concepts. Or maybe I'm not seeing what is required here. Can you propose the actual text that we could use in the docs?

[Chealer]

dmethvin, I looked at the page because I really did not know how to pass named functions, and I still do not know in depth. But before consulting the page, I tried passing by name (since that is how it works in PHP), and unless I misremember, that did not work (if I passed the string "foo", I would get an error). I ended up passing the function itself.

I won't write a text I am unsure about, but probably more important than the text would be to provide an example. Why not named();
Examples are always more helpful when they are plausible though - if the functions defined were not that dummy, the effect could be explained (e.g. "Display a message").

More generally, I would not call passing functions a basic concept. I agree the page cannot explain all JavaScript, but I think this should be an argument to focus on passing functions. If learning jQuery teaches a developer one thing about JavaScript, it will likely be callbacks.

Speaking of which, the Callback section does not show in the table of contents.

[AurelioDeRosa]

@dmethvin @mzgol I'm not sure that's a real action here. Should I try to submit a PR to tackle this issue?

[dmethvin]

I don't see a clear problem statement here so I can't help. @Chealer can you clarify what you thought should be done? Without some information I think we'd need to close this ticket.

[Chealer]

dmethvin, the Types page should explain how named functions can be passed. Or failing that, at least not pretend that "this page documents [...] all and everything you wanted to know about Functions."

I do not see what I could add to be more specific beyond what was already written.

[dmethvin]

I'm fine with removing the claim of "everything you wanted to know about Functions" since I don't think the jQuery API docs should be doing that. Opinions?

[kswedberg]

I agree with @dmethvin here. We should keep the docs focused and leave the comprehensive/encyclopedic resources to the likes of MDN.

[AurelioDeRosa]

That's my attempt to close this ticket: gh-850.

[Chealer]

Thank you for providing a reference, Aurelio. I think this could be a more specific link: https://developer.mozilla.org/docs/Web/JavaScript

[AurelioDeRosa]

Agree. PR updated.