[docs] UUID docs should say how to get "standard form" (issue 26267)
ammar at ammaraskar.com
ammar at ammaraskar.com
Thu Dec 8 19:52:02 EST 2016
On 2016/09/11 09:12:18, berkerpeksag wrote:
> https://bugs.python.org/review/26267/diff/18046/Doc/library/uuid.rst
> File Doc/library/uuid.rst (right):
>
>
https://bugs.python.org/review/26267/diff/18046/Doc/library/uuid.rst#newcode56
> Doc/library/uuid.rst:56: .. describe:: uuid1 == uuid2
> On 2016/08/06 05:20:17, ammar2 wrote:
> > On 2016/08/03 10:09:25, berkerpeksag wrote:
> > > Same as above. See datetime or decimal documentations for an
example of how
> to
> > > document comparison operations.
> >
> > So datetime takes the approach of documenting operators in a table
(presumably
> > because it has a lot of ops)
> > https://docs.python.org/3/library/datetime.html#datetime.date.day
> >
> > decimal seems to do it in this way
> >
https://docs.python.org/3/library/decimal.html#decimal.Decimal.compare
> >
> > The style I used here is from
> > https://docs.python.org/3/library/stdtypes.html#set but now that I
look at it,
> > within the stdtypes there's also the datetime style operator
documentation for
> > numbers.
> >
>
https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex
> >
> > Is there a preferred style for documenting operators? Which one
should I use
> > here?
> >
> > (apparently I forgot to click the publish button on Rietveld, I
wrote this day
> > before yesterday)
>
> Sorry, I wasn't very clear in my earlier message. I was referring to
the
> following paragraph in datetime documentation:
>
> Comparisons of timedelta objects are supported with the timedelta
object
> representing the smaller duration considered to be the smaller
timedelta. In
> order to stop mixed-type comparisons from falling back to the default
comparison
> by object address, when a timedelta object is compared to an object of
a
> different type, TypeError is raised unless the comparison is == or !=.
The
> latter cases return False or True, respectively.
>
> https://docs.python.org/3/library/datetime.html#timedelta-objects
>
> In other words, instead of using too much markup, it would be nice to
document
> that it supports comparison operators in prose.
I've updated it so the comparison operators are explain in prose but
there's still markup for the str() operator.
http://bugs.python.org/review/26267/
More information about the docs
mailing list