Code

Opened 8 years ago

Closed 8 years ago

Last modified 8 years ago

#2834 closed defect (wontfix)

Indents in base.py comments breaks epydoc doc generation.

Reported by: anonymous Owned by: adrian
Component: Core (Other) Version: master
Severity: minor Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

Running the Epydoc document generator on a model returns the following error message:

File: c:\dev\python-2.4.2\lib\site-packages\django\db\models\base.py, line
243, in django.db.models.base.Model._collect_sub_objects
Lines 246, 247: Improper paragraph indentation

Looking at those lines, we find:

    def _collect_sub_objects(self, seen_objs):
        """
        Recursively populates seen_objs with all objects related to this object.
        When done, seen_objs will be in the format:
            {model_class: {pk_val: obj, pk_val: obj, ...},
             model_class: {pk_val: obj, pk_val: obj, ...}, ...}
        """

The problem appears to be with the extra tabs in the last two lines of that comment. I've fixed it in my local version, but someone may want to fix the version in the repository so it doesn't break for others.

Attachments (0)

Change History (1)

comment:1 Changed 8 years ago by mtredinnick

  • Resolution set to wontfix
  • Status changed from new to closed

Removing indentation (they are spaces, not tabs, by the way) that makes the docstring easier to read is not the "solution" here. I don't think we should put in epydoc-specific formatting to solve this (it would need a double-colon at the end of the preceeding line) at the moment, either, since we haven't really made a decision about which API-documentation tool(s) to support. There are a few around and epydoc isn't a clear winner, by any means (although it's similarlity to ReST is a plus).

Closing this as "wontfix" for now, but you may want to start a thread on django-devel discussing the various API documentation tools so that we can make a decision about which formatting oddities we are willing to put into the docstrings.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.