Opened 12 years ago

Closed 12 years ago

Last modified 12 years ago

#2834 closed defect (wontfix)

Indents in comments breaks epydoc doc generation.

Reported by: (none) Owned by: Adrian Holovaty
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:


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\, 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.

Change History (1)

comment:1 Changed 12 years ago by Malcolm Tredinnick

Resolution: wontfix
Status: newclosed

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.

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