classification
Title: distutils doc contains lots of XXX
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: docs@python, eric.araujo, flox, georg.brandl, python-dev, tarek
Priority: normal Keywords:

Created on 2012-01-05 19:02 by flox, last changed 2012-02-26 03:21 by eric.araujo. This issue is now closed.

Messages (9)
msg150683 - (view) Author: Florent Xicluna (flox) * (Python committer) Date: 2012-01-05 19:02
http://docs.python.org/distutils/apiref.html?highlight=XXX#module-distutils.ccompiler

We find lots of "XXX" and "XXX see also." which give no information.
msg150745 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-06 16:54
Tarek ruled that time spent improving the distutils docs was time lost and better spent on distutils2.  Accordingly, I only fix clear bugs in the doc but don’t improve them in any way.  I’m inclined to close this as wontfix, or I can remove the XXX if you’re strongly against them.  (For the packaging docs, I will fix them properly.)
msg150793 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-01-07 12:57
I would make comments out of the XXX, and if a whole section is just that XXX, remove the section as well.
msg150798 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-07 14:47
These are the XXX:

  XXX true? does ANSI say anything about this?
  XXX defaults to what?
  XXX see also.
  XXX see also.
  XXX see also.
  XXX see also.
  XXX see also.

The first two are questions that can be answered, and when I research them for the packaging docs I could also backport the changes to the distutils docs; what to do for the other instances is less clear, so just deleting may be better than turning them into comments that will never get solved.
msg150800 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-01-07 14:51
Agreed.
msg150801 - (view) Author: Florent Xicluna (flox) * (Python committer) Date: 2012-01-07 15:06
The proposed solution is ok.

It sounds like unfinished documentation when you hit an "XXX".
For the "/dev/" documentation, it's OK, but for the released version, we should avoid it.
msg152686 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-02-05 12:50
New changeset 3d25869fce0c by Éric Araujo in branch '3.2':
Hide or remove user-visible XXX notes from distutils doc (#13716).
http://hg.python.org/cpython/rev/3d25869fce0c

New changeset 1cb9b8126534 by Éric Araujo in branch 'default':
Merge edits from 3.2 (#13716, #1040439, #2945, #13770, #6715)
http://hg.python.org/cpython/rev/1cb9b8126534
msg154299 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-02-26 02:49
New changeset e853ea9efc6e by Éric Araujo in branch '2.7':
Hide or remove user-visible XXX notes from distutils doc (#13716).
http://hg.python.org/cpython/rev/e853ea9efc6e
msg154307 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-26 03:21
Done.
History
Date User Action Args
2012-02-26 03:21:50eric.araujosetstatus: open -> closed
type: behavior -> enhancement
messages: + msg154307

resolution: fixed
stage: needs patch -> resolved
2012-02-26 02:49:09python-devsetmessages: + msg154299
2012-02-05 12:50:14python-devsetnosy: + python-dev
messages: + msg152686
2012-01-07 15:06:49floxsetmessages: + msg150801
2012-01-07 14:51:36georg.brandlsetmessages: + msg150800
2012-01-07 14:47:05eric.araujosetassignee: docs@python -> eric.araujo
messages: + msg150798
2012-01-07 12:57:39georg.brandlsetnosy: + georg.brandl
messages: + msg150793
2012-01-06 16:54:12eric.araujosetmessages: + msg150745
2012-01-05 19:04:00floxsetnosy: + tarek, eric.araujo

versions: + Python 3.2, Python 3.3
2012-01-05 19:02:15floxcreate