Opened 13 years ago

Closed 13 years ago

Last modified 13 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: no UI/UX: no

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 by Russell Keith-Magee, 13 years ago

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 by slinkp@…, 13 years ago

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 by Gabriel Hurley, 13 years ago

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 by Gabriel Hurley, 13 years ago

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 by Gabriel Hurley, 13 years ago

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