Code

Opened 6 years ago

Closed 6 years ago

#8956 closed (invalid)

doctests should not be used in regular documentation outside the orm

Reported by: simon Owned by: nobody
Component: Uncategorized Version: 1.0
Severity: Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

The forms docs for example really shouldn't be using doctest style.

Attachments (0)

Change History (2)

comment:1 Changed 6 years ago by telenieko

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

Could the submiter please elaborate a bit more the Description, for us non-native English speakers! I understood:

"""The Examples in the Forms documentations shouldn't be using Doctest style."""

Am I right? In that case I doubt that's really a bug, doctests are used for documentation because they exemplify things, (that is: You type This, You get That).

comment:2 Changed 6 years ago by mtredinnick

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

This ticket doesn't really make sense. Forbidding examples in docstrings would be bad style. If there are places where the examples are confusing, rather then enlightening, or drown out the real description, patches to clarify/remove would be useful. If you're worried that people might think those examples are actually run as tests, a patch to contributing.txt or a patch to the testing framework to run the doctests would be useful.

But the general statement in the ticket description wouldn't be a good road to go down. Docstrings should be as clear as possible and doctest happened to choose (re-use) a style that was particularly clear. Using that style without it being a doctest is fine.

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.