bug#29023: 25.3; newsticker: Inconsistent documentation of newsticker-new-item-functions

[Tim Landscheidt]

(newsticker) Automatic Processing says:

|    […]

|    In order to do so write a function which takes three arguments

| FEED
|      the name of the corresponding news feed,
| TITLE
|      the title of the headline,
| DESC
|      the decoded description of the headline.

|    and add it to ‘newsticker-new-item-functions’.  […]

newsticker-new-item-functions's docstring says:

| List of functions run after a new headline has been retrieved.
| Each function is called with the following three arguments:
| FEED  the name of the corresponding news feed,
| TITLE the title of the headline,
| DESC  the decoded description of the headline.

However the functions "Hook samples" in newst-backend.el are
all defined as:

| […]
| (defun newsticker-new-item-functions-sample (feed item)
| […]

| (defun newsticker-download-images (feed item)
| […]

| (defun newsticker-download-enclosures (feed item)
| […]

i. e. they take two arguments, not three.

Also, there is no explicit documentation if the functions'
return values matter (AFAIUI they are ignored).

In addition, newsticker-new-item-functions's docstring re-
commends:

| […]

| See ‘newsticker-download-images’, and
| ‘newsticker-download-enclosures’ for sample functions.

| […]

It might be useful to add
newsticker-new-item-functions-*sample* to that list :-).