Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#15504 closed (fixed)

Incorrect docs for args to SyndicationFeed.add_item

Reported by: slinkp@… Owned by: nobody
Component: Documentation Version: 1.2
Severity: Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

The docs at http://docs.djangoproject.com/en/1.2/ref/contrib/syndication/#syndicationfeed-classes
say that SyndicationFeed.add_item takes only keyword args.
In fact as per http://docs.djangoproject.com/en/dev/ref/utils/#syndicationfeed there are three positional args followed by keyword args:

    def add_item(self, title, link, description, author_email=None,
        author_name=None, author_link=None, pubdate=None, comments=None,
        unique_id=None, enclosure=None, categories=(), item_copyright=None,
        ttl=None, **kwargs):

If you try to pass those first three as kwargs it blows up with a TypeError.

Change History (5)

comment:1 Changed 6 years ago by Russell Keith-Magee

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Resolution: invalid
Status: newclosed

I can't work out what you're reporting here. There are three required arguments, and a series of optional arguments. You need to specify all of the required arguments, and all usual Python argument semantics apply. I can't see anything confusing in the existing text.

comment:2 Changed 6 years ago by slinkp@…

Component: UncategorizedDocumentation
Resolution: invalid
Status: closedreopened

Sorry, I may have confused things a bit by linking to both 1.2 and dev docs, my mistake.
I was trying to say that the args are documented in two places in the docs, and they disagree.

http://docs.djangoproject.com/en/dev/ref/utils/#syndicationfeed is correct.

http://docs.djangoproject.com/en/dev/ref/contrib/syndication/#syndicationfeed-classes is wrong, it says:

SyndicationFeed.add_item(**kwargs)

    Add an item to the feed with the given parameters.

    Required keyword arguments are:

        * title
        * link
        * description

That should be replaced by:

SyndicationFeed.add_item(title, link, description, **kwargs)

    Add an item to the feed with the given parameters.

comment:3 Changed 6 years ago by Gabriel Hurley

Triage Stage: UnreviewedAccepted

Agreed that the two are inconsistent. Particularly it's /ref/contrib/syndication/ that needs to be fixed. The first three arguments there are positional arguments, not keyword arguments, and it's worth enumerating the arguments as in the other doc linked.

Moreover, the crossref targets for those docs are a total disaster. Neither django.contrib.syndication.django.utils.feedgenerator.SyndicationFeed nor django.contrib.syndication.SyndicationFeed exist. That whole section needs to be fixed up.

comment:4 Changed 6 years ago by Gabriel Hurley

Resolution: fixed
Status: reopenedclosed

In [15739]:

Fixed #15504 -- Cleaned up contrib.syndication and contrib.utils.feedgenerator docs. Corrected numerous reST problems, removed duplicate method declarations, corrected method signatures, etc. Thanks to slinkp for the report.

comment:5 Changed 6 years ago by Gabriel Hurley

In [15740]:

[1.2.X] Fixed #15504 -- Cleaned up contrib.syndication and contrib.utils.feedgenerator docs. Corrected numerous reST problems, removed duplicate method declarations, corrected method signatures, etc. Thanks to slinkp for the report.

Backport of [15739] from trunk.

Note: See TracTickets for help on using tickets.
Back to Top