Opened 7 years ago

Closed 7 years ago

#13756 closed enhancement (fixed)

fix developer manual docstrings

Reported by: vbraun Owned by: mvngu
Priority: major Milestone: sage-5.6
Component: documentation Keywords:
Cc: Merged in: sage-5.6.beta0
Authors: Volker Braun Reviewers: Keshav Kini
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description

The example docstrings often violate PEP-257 ;-)

Attachments (1)

trac_13756_documentation.patch (4.4 KB) - added by vbraun 7 years ago.
Initial patch

Download all attachments as: .zip

Change History (8)

comment:1 Changed 7 years ago by kini

In doc/en/developer/conventions.rst , "Convert this integer in the multi-precision floating real field R" should be something like "Convert this integer into an element of the multi-precision floating real field R".

Actually since that sort of sounds like state is being mutated, and the original doesn't. Why not keep the original wording and turn "Returns" into "Return a"?

Changed 7 years ago by vbraun

Initial patch

comment:2 Changed 7 years ago by vbraun

  • Reviewers set to Keshav Kini
  • Status changed from new to needs_review

Fine

comment:3 Changed 7 years ago by kini

  • Status changed from needs_review to positive_review

OK, looks good :)

comment:4 Changed 7 years ago by novoselt

Thank you! "This function returns" always bugged me but I didn't do anything. While we are at it - what about articles? Why "a string", but just "integer"? (In the case here I would actually prefer "a positive integer".)

comment:5 follow-up: Changed 7 years ago by vbraun

Aren't you Russian? You are not supposed to use articles at all ;-)

Seriously, I think both is fine. Personally I'd prefer no indefinite article since it doesn't convey any extra information: "string" is shorter than "a string". But its such a minor detail that I don't think we should elaborate on it in the manual.

Similarly, I don't think that "a positive integer" vs. "integer $>0$" merits having an official policy. Both are easily comprehensible.

comment:6 in reply to: ↑ 5 Changed 7 years ago by novoselt

Replying to vbraun:

Aren't you Russian? You are not supposed to use articles at all ;-)

And so I did not, but you did, and I was irritated by inconsistency in toric docstrings, such irritations transcend national tastes ;-) So I don't care much about the choice, but one would be nice.

comment:7 Changed 7 years ago by jdemeyer

  • Merged in set to sage-5.6.beta0
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.