UUID docs should say how to get "standard form"

[Evelyn Mitchell]

str() does not return the uuid within {}, line 53 should be changed to show
that.

[Evelyn Mitchell]

Thanks for adding the comparison at 56:58, that's a significant thing to know.

[berkerpeksag]

http://bugs.python.org/review/26267/diff/18046/Doc/library/uuid.rst
File Doc/library/uuid.rst (right):

http://bugs.python.org/review/26267/diff/18046/Doc/library/uuid.rst#newcode51
Doc/library/uuid.rst:51: .. describe:: str(uuid)
It would be better to be less verbose here. This can go after the "Exactly one
of hex, bytes, bytes_le, fields [...]" paragraph in the uuid.UUID()
documentation.

http://bugs.python.org/review/26267/diff/18046/Doc/library/uuid.rst#newcode56
Doc/library/uuid.rst:56: .. describe:: uuid1 == uuid2
Same as above. See datetime or decimal documentations for an example of how to
document comparison operations.

[ammar2]

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/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)

[berkerpeksag]

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.

[ammar2]

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.