[issue16665] doc for builtin hex() is poor

[rurpy]

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 <report at bugs.python.org>
<http://bugs.python.org/issue16665>
_______________________________________