Indents in base.py comments breaks epydoc doc generation.

[(none)]

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.

[Malcolm Tredinnick]

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.