[New-bugs-announce] [issue16665] doc for builtin hex() is poor

[rurpy the second]

New submission from rurpy the second:

The documentation of the hex() builtin function is poor.  Specifically it does not say (directly) that:

1. The resulting string is prefixed with "0x".

2. Any a-f characters used are lower case.

3. Negative integers are converted by prefixing a minus sign to hex() of the absolute value of the argument.

4. It should have a cross reference to the %x format of the "%" operator with a note that it is more veratile than the hex() builtin. 

5. It should have a cross reference to the way of performing the inverse operation: hex->int

I am not a good writer but here is an attempt at improving it:

--------
Convert an integer number to a hexadecimal string.  The resulting string is prefixed with "0x" and any alpha characters a-f are lowercase ascii.  Negative integers are converted to hex(abs(x)) prefixed with "-".  In all cases the result is a valid Python expression.

If x is not a Python int object, it has to define an __index__() method that returns an integer.

Note: For another more flexible way of converting an integer to hexadecimal see the "x" and "X" conversion types in link:[4.7.2 -  printf-style String Formatting] and link:[6.1.3.1 - Format Specification Mini-Language]

Note: To convert a hexadecimal string to an integer, use link:[int()] with a radix argument of 16. 

Note: To obtain a hexadecimal string representation for a float, use the link:[float.hex()] method.
--------

----------
assignee: docs at python
components: Documentation
messages: 177352
nosy: docs at python, rurpy2
priority: normal
severity: normal
status: open
title: doc for builtin hex() is poor
versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue16665>
_______________________________________