How do I find documentation?
As I mentioned in the comment: Ask Emacs!. Emacs has wonderful documentation (as @Tyler describes in his answer), but equally importantly, it provides methods to search and read that documentation effectively and efficiently.
The Help system can be accessed with the C-h prefix: if you do C-h ?, you'll get a list of keys that you can use to get help, e.g. f will give you help on functions, v does the same for variables. I would highly recommend that you go through each and every one of those keys to get an idea of what's available.
Emacs also provides the Info system for reading and searching the manuals: doing C-h i will give you a list of the manuals that are installed on your system. The first manual I would read would be the Info manual itself: say C-h i m Info and have at it. To quote myself: "Learning to use the Help system and the Info manuals is much more productive than endless googling." @Tyler points out two other, very important manuals: the Emacs manual and the Emacs Lisp manual. However, instead of reading them on the web, I would recommend that you read them in Emacs itself: say C-h i g(emacs) or C-h i g(elisp) to go to the indicated manual, then use the stuff you learnt from the Info manual to find your way around each of the other manuals.
What does &optional and &rest and map and props mean?
When the help system shows the syntax of the function to be
(tool-bar-add-item-from-menu COMMAND ICON &optional MAP &rest PROPS) , that tells you that the function takes two mandatory arguments (COMMAND and ICON), a third optional argument (MAP) and, starting from the fourth position, an arbitrary number of other arguments which are grouped together in a list (PROPS). All of this is explained in the section of the Emacs Lisp manual entitled "Features of Argument Lists" which you can get to with C-h i g(elisp)argument list. The doc string of the function that you get with C-h f tool-bar-add-item-from-menu tells you that
the function does the following:
Define tool bar binding for COMMAND in keymap MAP using the given ICON.
This makes a binding for COMMAND in ‘tool-bar-map’, copying its
binding from the menu bar in MAP (which defaults to ‘global-map’), but
modifies the binding by adding an image specification for ICON. It
finds ICON just like ‘tool-bar-add-item’. PROPS are additional
properties to add to the binding.
Now, command is a symbol that refers to an (ahem) command, i.e. a function with an interactive spec. The doc string does not tell you that, but given a bit of experience (i.e. knowing that there is something called a command in Emacs Lisp), you can guess what it is. The only surefire way to know however is to find more documentation for it. You can try the Emacs Manual with C-h i g(emacs)i tool-bar-add-item-from-menu but that doesn't give us anything, so try the Elisp manual instead with C-h i g(elisp)i tool-bar-add-item-from-menu. You'll end up in the same "Tool Bar" section that @Tyler pointed you to above, but instead of reading it in the browser, you'll be reading it in Emacs.
Here are ways to use Info to get to the sections of the Elisp manual that @Tyler provides links to above. First get into the Elisp manual with C-h i g(elisp). Once you are in a manual, then navigation within that manual does not require that initial C-h i g(elisp).
- keymaps:
m keymaps
- menu keymaps:
i menu-k<TAB> - note that there is TAB completion.
- tool bars:
i tool-b<TAB>'
But as @Tyler implies, this example is more complicated than many other functions, because it assumes that you know something about keymaps and menus and tool bars and just uses those concepts without explanation. To use a (possibly bad) analogy: if you don't know much about calculus, then trying to calculate the area of a circle with an integral is probably not a good way to go about learning the subject: you'd start with simpler examples (e.g finding the area under a parabola between some limits).
What is the nil for?
As explained above, the nil in the call is the third argument, so it corresponds to the map argument: the function is called with a null keymap. If there was nothing following, you could leave it out: it's an optional argument. However, there is something following: a property (i.e a pair of items: a property name and a property value), and since you want that to be associated with the props argument, you need to make sure to specify a value for the map argument as well. If you didn't include the nil: (tool-bar-add-item-menu command icon :label "foo") then the third argument is the :label symbol and that would be bound to map, leaving only "foo" for the props argument: confusion would reign and you'd probably end up with an error.
