[issue16665] doc for builtin hex() is poor
Jessica McKellar added the comment: 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 -- nosy: +jesstess stage: needs patch - patch review Added file: http://bugs.python.org/file34435/issue16665_2.patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Raymond Hettinger added the comment: Approved. You can go ahead and apply this. -- assignee: rhettinger - jesstess ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Changes by Terry J. Reedy tjre...@udel.edu: -- versions: -Python 3.2 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Roundup Robot added the comment: 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 -- nosy: +python-dev resolution: - fixed stage: patch review - committed/rejected status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Antoine Pitrou added the comment: Jessica doesn't have commit rights, so I committed this myself. Also added an example of the funny hex(long) behaviour in Python 2. -- nosy: +pitrou ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Michael Dickens added the comment: I used the wording suggested by rurpy with some changes. I also added a few examples. -- keywords: +patch nosy: +MTGandP Added file: http://bugs.python.org/file30882/issue16665.diff ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Raymond Hettinger added the comment: 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. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Changes by Martin Kysel mar...@martinkysel.com: -- nosy: +mkysel ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
rurpy added the comment: 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.) -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Changes by Terry J. Reedy tjre...@udel.edu: -- nosy: +terry.reedy ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Changes by Éric Araujo mer...@netwok.org: -- nosy: +eric.araujo ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
rurpy added the comment: 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. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
rurpy added the comment: 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. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
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@python components: Documentation messages: 177352 nosy: docs@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 rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Ezio Melotti added the comment: +1 -- keywords: +easy nosy: +ezio.melotti stage: - needs patch type: - enhancement versions: -Python 2.6, Python 3.1 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Raymond Hettinger added the comment: -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. -- assignee: docs@python - rhettinger nosy: +rhettinger ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16665] doc for builtin hex() is poor
Ezio Melotti added the comment: 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). -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16665 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
