classification
Title: doc for builtin hex() is poor
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: jesstess Nosy List: Michael Dickens, docs@python, eric.araujo, ezio.melotti, jesstess, mkysel, pitrou, python-dev, rhettinger, rurpy2, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2012-12-11 20:33 by rurpy2, last changed 2014-03-16 01:20 by pitrou. This issue is now closed.

Files
File name Uploaded Description Edit
issue16665.diff Michael Dickens, 2013-07-09 23:57 patch for issue 16665
issue16665_2.patch jesstess, 2014-03-15 18:27 review
Messages (13)
msg177352 - (view) Author: rurpy (rurpy2) Date: 2012-12-11 20:33
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.
--------
msg177354 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-12-11 20:42
+1
msg177365 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-12-12 06:11
-1 for the suggested text.

For some of the points, a couple examples will do a better job of explaining hex() that trying to write-out the full code specification in prose.  

Overly wordy documentation is harder to use than something short that addresses the primary use case.  

Also, the suggested "notes" editorialize and venture into the realm of personal coding preferences.
msg177366 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-12-12 06:24
FTR my +1 was about the suggestion, not the proposed text.
The first 3 points can be explained with an example, the last 2 can be added in the prose.  I also agree that notes are not necessary (especially if they use the "note" rst directive).
msg177384 - (view) Author: rurpy (rurpy2) Date: 2012-12-12 18:20
Raymond Hettinger (rhettinger) msg177365:
> For some of the points, a couple examples will do a better job of explaining hex() that trying to write-out the full code specification in prose.  

Examples should never substitute for a clear, complete and concise description.  Examples serve to illustrate and clarify a description.  An example can only describe usage at a single point in the solution space.  The prose description (when well written) describes the total solution space.  

> Overly wordy documentation is harder to use than something short that addresses the primary use case.

No comments in this issue have suggested providing an "overly wordy" description.  The suggestion was for wording that accurately and concisely describes the behavior of the hex() function.  That is what good reference material is supposed to do.

Reference documentation should describe the behavior of its subject including any corner cases.  Addressing only "the primary use case" is not sufficient.  For addressing the primary use case, supplement the prose with an example.

> Also, the suggested "notes" editorialize and venture into the realm of personal coding preferences.

That characterization is incorrect.  
 
There is no editorializing (if this in reference to the word "flexible" in the note).  It is a fact that string formatting with the %x specifier also converts to hex and offers more control over the output than the hex() function does.  A reader interested in the hex() function should be apprised of this alternative.  Perhaps there is some other word that you would find more neutral than "flexible"?

There is no venturing into personal coding preferences -- only the factual and appropriate mention of an alternative.

One of the cheapest, easiest ways of improving documentation is good cross-referencing to related items.
msg177429 - (view) Author: rurpy (rurpy2) Date: 2012-12-13 18:22
An ammendment to my proposed doc change.

Replace the text (which is unchanged from the current doc),

  "...the result is a valid Python expression"

with,

  "...the result is a valid Python "hexinteger" literal (see link:[Python Lang Ref, sec 2.4.4. Integer literals])

"Python epression" in the current doc is way more non-specific than it need be.  The result is not any old python expression, it is a very specific type of python expression so the doc should say that.
msg178089 - (view) Author: rurpy (rurpy2) Date: 2012-12-24 19:09
I would like to submit the following post made to c.l.p in support of my claim that a cross-reference to the string formatting "x" format specifier would be desireable in the documentation for the hex() builtin:

  Newsgroups: comp.lang.python
  Subject: Re: Integer as raw hex string?
  Date: Mon, 24 Dec 2012 11:21:15 -0500
  https://groups.google.com/group/comp.lang.python/msg/054706d112f6385d?hl=en

(In case the link goes away... the post asks how to get the same results as hex() but without the leading "0x".)
msg192786 - (view) Author: Michael Dickens (Michael Dickens) Date: 2013-07-09 23:57
I used the wording suggested by rurpy with some changes. I also added a few examples.
msg192787 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-07-10 01:03
Personally, I think this is overkill.  Can you capture the essence of what you want to say in something short and sweet that gets to the point?  We're not looking for a complete spec.  You just need to say basically what the function does.
msg213670 - (view) Author: Jessica McKellar (jesstess) * (Python triager) Date: 2014-03-15 18:27
Thanks for the patch, Michael!

There's a small doc build issue with your patch: the note on int shows up inside the code block for the examples.

In response to rhettinger's feedback I've attached a slightly more compact patch that hits the highlights. I checked that the docs build cleanly with the patch and that the output looks visually as expected.

I think both patches are an improvement over the current docs.

=> review
msg213682 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-03-15 20:28
Approved.  You can go ahead and apply this.
msg213695 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-16 01:17
New changeset 464c22bf9fe1 by Antoine Pitrou in branch '3.3':
Close #16665: improve documentation for hex().  Patch by Jessica McKellar.
http://hg.python.org/cpython/rev/464c22bf9fe1

New changeset d14beaf03f55 by Antoine Pitrou in branch '2.7':
Close #16665: improve documentation for hex().  Patch by Jessica McKellar.
http://hg.python.org/cpython/rev/d14beaf03f55

New changeset c267f4eb8173 by Antoine Pitrou in branch 'default':
Close #16665: improve documentation for hex().  Patch by Jessica McKellar.
http://hg.python.org/cpython/rev/c267f4eb8173
msg213696 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-03-16 01:20
Jessica doesn't have commit rights, so I committed this myself.
Also added an example of the funny hex(long) behaviour in Python 2.
History
Date User Action Args
2014-03-16 01:20:05pitrousetnosy: + pitrou
messages: + msg213696
2014-03-16 01:17:03python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg213695

resolution: fixed
stage: patch review -> resolved
2014-03-15 21:45:23terry.reedysetversions: - Python 3.2
2014-03-15 20:28:56rhettingersetassignee: rhettinger -> jesstess
messages: + msg213682
2014-03-15 18:27:45jesstesssetfiles: + issue16665_2.patch

nosy: + jesstess
messages: + msg213670

stage: needs patch -> patch review
2013-07-10 01:03:23rhettingersetmessages: + msg192787
2013-07-09 23:57:33Michael Dickenssetfiles: + issue16665.diff

nosy: + Michael Dickens
messages: + msg192786

keywords: + patch
2013-07-01 16:43:44mkyselsetnosy: + mkysel
2012-12-24 19:09:09rurpy2setmessages: + msg178089
2012-12-15 18:33:08terry.reedysetnosy: + terry.reedy
2012-12-13 18:22:02rurpy2setmessages: + msg177429
2012-12-13 16:38:54eric.araujosetnosy: + eric.araujo
2012-12-12 18:20:17rurpy2setmessages: + msg177384
2012-12-12 06:24:48ezio.melottisetmessages: + msg177366
2012-12-12 06:11:35rhettingersetassignee: docs@python -> rhettinger

messages: + msg177365
nosy: + rhettinger
2012-12-11 20:42:05ezio.melottisettype: enhancement
versions: - Python 2.6, Python 3.1
keywords: + easy
nosy: + ezio.melotti

messages: + msg177354
stage: needs patch
2012-12-11 20:33:17rurpy2create