[Pythonmac-SIG] Fixing the documentation...

[has]

Ronald Oussoren wrote:

>>>       2.1 macpath -- MacOS path manipulation functions
>>
>>Deprecate. Also note that the 2.4.3 documentation now says "It can be used to manipulate old-style Macintosh pathnames on Mac OS X (or any other platform)." which is incorrect (it uses POSIX-style paths), so delete that sentence.
>
>I'm not a native english speaker, but I read this as "you can use this to manipulate OS9 style paths on any platform".

Note that the above sentence was only added in the 2.4 docs. If you can find a way to make it do HFS paths then let me know, otherwise the sentence needs to be deleted and the module itself should be deprecated (i.e. folk should be using os.path anyway).


>As I mentioned in another message this module might be useful to work with OS9-style paths as used by some Carbon API's.
>>
>>>       2.4 MacOS -- Access to Mac OS interpreter features
>>
>>Get/SetCreatorAndType should really be fixed or deprecated as they don't appear to work for bundle-based files.
>
>They should be fixed. Why does everyone want to remove what they don't quite understand?

Fix or deprecate; doesn't bother me which as long as it's done.

Bear in mind, however, that file typing has gotten a lot more complicated since OS 9 days, so this API has been grossly inadequate for the job for a long time now. Deprecating it would just be an honest admission of that fact; heck, might even encourage folks to come up with a modern replacement.

And deprecation doesn't stop anyone using it in the meantime, of course, but considering it's been in this state for the last five years I doubt many are. :)



>One of the strong points of python on the mac is that it is one of the *very* few languages that provides bindings to most parts of the system APIs. IMHO the bindings to Carbon suck, but that doesn't mean we should scrap or completely hide them.



>I'd love to deprecate Carbon.CF as well, but we can't do that until we have another way to access those APIs. PyObjC is about this > < close to doing that, I just haven't gotten around finishing the final bits yet.

As Bob says, Carbon.CF is pretty incomplete, broken and weird so is not a great deal of use as-is. I imagine that's why he said deprecate, since unless someone wants to do a major overhaul then it's not much better than useless anyway. (FWIW, I'd prefer to see it overhauled, but I ain't the one to do it, so...:)


>>>       4.2 Carbon.AH -- Apple Help
>>
>>Do nothing.
>
>Documentation would be nice :-)

Yeah, but let's finish cleaning up the existing material first, since that can be done in time for 2.5's release. If we wait for comprehensive new documentation to be completed first then nothing'll get done for 2.5 and we'll be back having this same discussion come 2.6. ;)


>>>       4.10 Carbon.Evt -- Event Manager
>>
>>Deprecate, or at least add note to use modern alternative. Superceded by CarbonEvt.
>
>Don't deprecate but not that you should CarbonEvt and that Apple has deprecated the Event Manager API.

If Apple have deprecated the original Carbon API then I think it makes very good sense to deprecate the Python wrapper for that API as well. That way, no surprises if/when Apple decide to break it/drop it. We're just following their lead.

The only exception might be where we don't have a wrapper for the new API that supercedes it, in which case we should leave it undeprecated but add a warning note. In the case of Carbon.Evt, we have Carbon.CarbonEvt, so I don't think deprecation is too strong a statement to make. It says nothing about if/when a module will be removed (if ever); only that sensible folks should avoid its use in any future projects, and may want (or need) to update any existing dependent code at some point.

has
-- 
http://freespace.virgin.net/hamish.sanderson/