为什么 PyObjC 文档如此糟糕？ [关闭]答案

【问题标题】：Why is the PyObjC documentation so bad? [closed]为什么 PyObjC 文档如此糟糕？ [关闭]
【发布时间】：2010-09-06 01:52:40
【问题描述】：

例如，http://developer.apple.com/cocoa/pyobjc.html 仍然适用于 OS X 10.4 Tiger，而不是 10.5 Leopard。这是 Apple 的官方文档。

PyObjC 官方页面同样糟糕，http://pyobjc.sourceforge.net/

这太糟糕了，令人费解.. 我正在考虑学习 Ruby，主要是因为 RubyCocoa 的东西有更好的文档记录，而且有很多不错的教程（例如http://www.rubycocoa.com/），并且因为鞋子 GUI 工具包..

即使this badly-auto-translated Japanese tutorial 比我能找到的其他文档更有用..

我只想用 Cocoa GUI 创建相当简单的 Python 应用程序。
任何人都可以阐明可怕的文档，或者指出一些教程，这些教程不只是给你大量的代码，并假设你知道 NSThread.detachNewThreadSelector_toTarget_withObject_("queryController", self, None) 做了什么......？

【问题讨论】：

您链接到的第一个 PyObjC 教程是 Jonathan Rentzsch 的一篇文章（您可以在视频中听到他的声音，并且您可以从 C4 视频中认出它）。尽管它在 Apple 的网站上没有署名，但它并不是由 Apple 编写和维护的“Apple 文档”。

标签： python macos cocoa pyobjc

【解决方案1】：

PyObjC 缺乏文档的主要原因是只有一个开发人员（我），而作为大多数开发人员，我并不特别喜欢编写文档。因为 PyObjC 对我来说是一个副项目，所以我倾向于专注于功能和错误修复，因为这对我来说更有趣。

改进文档的最佳方法是自愿在 pyobjc-dev 邮件列表中提供帮助。

顺便说一句：pythonmac-sig 邮件列表（参见 google）是在 MacOSX（不仅仅是 PyObjC）上获得 Python 帮助的绝佳资源。

【讨论】：

【解决方案2】：

我同意该教程存在缺陷，将随机的、无法解释的代码扔在您的眼前。它介绍了诸如自动释放池和用户默认值之类的概念，但没有解释您为什么想要它们（“用于内存管理的自动释放池”很难解释）。

也就是说……

基本上我想做的就是编写 Cocoa 应用程序，而不必学习 ObjC。

恐怕暂时，您需要对 ObjC 有基本的了解才能从任何使用 Cocoa 的语言中受益。 PyObjC、RubyCocoa、Nu 等充其量只是小众，它们都是由非常熟悉 ObjC 和 Cocoa 来龙去脉的人开发的。

目前，如果您真正看到这些桥梁在脚本语言真正大放异彩的地方很有用，而不是尝试用它们构建整个应用程序，您将受益最大。虽然这个已经完成了（使用 LimeChat，我现在正在使用一个 RubyCocoa 编写的应用程序），但这种情况很少见，而且可能会持续一段时间。

【讨论】：

【解决方案3】：

说白了：

如果你想成为一名高效的 Cocoa 程序员，你必须学习 Objective-C。故事结束。

Python 或 Ruby 都不能通过各自的桥梁替代 Objective-C。您仍然需要了解 Objective-C API、NSObject 派生类的固有行为以及 Cocoa 的许多其他细节。

PyObjC 和 RubyCocoa 是从 Cocoa 应用程序访问 Python 或 Ruby 功能的好方法，包括大部分（如果不是完全）用 Python 或 Ruby 构建 Cocoa 应用程序。但其中的成功是建立在对 Cocoa 及其组成的 Objective-C API 的透彻理解之上的。

【讨论】：

【解决方案4】：

Tom 和 Martin 的回答绝对正确（在几乎任何开源项目中，您都会发现大多数贡献者都对开发特别感兴趣；对半相关的事情不太感兴趣例如文档），但我认为您最后的特定问题不太适合 PyObjC 文档。

NSThread.detachNewThreadSelector_toTarget_withObject_("queryController", self, None)

NSThread 是 Cocoa API 的一部分，因此 documented over at Apple，包括特定方法 + detachNewThreadSelector:toTarget:withObject:（我会链接到那里，但显然 stackoverflow 有解析它的错误）。 CocoaDev wiki also has an article.

我认为 PyObjC 尝试记录 Cocoa 不是一个好主意，除了一些如何在 Python 中使用它的基本示例。解释选择器也可能超出了 PyObjC 的范围，因为它们也是 Objective-C 的一个特性，而不是 PyObjC 的一个特性。

【讨论】：

【解决方案5】：

我偶然发现了一个关于 PyObjC/Cocoa 的好教程：

http://lethain.com/entry/2008/aug/22/an-epic-introduction-to-pyobjc-and-cocoa/

【讨论】：

【解决方案6】：

我想要做的就是使用 Cocoa GUI 创建相当简单的 Python 应用程序。任何人都可以阐明可怕的文档，或者指点我一些教程，这些教程不只是给你大量代码并假设你知道什么NSThread.detachNewThreadSelector_toTarget_withObject_("queryController", self, None) 会..？

[...]

基本上我想做的就是编写 Cocoa 应用程序，而不必学习 ObjC。

虽然我基本上同意 Soeren 的回答，但我会更进一步：

在您不了解 Objective C 的情况下使用 Cocoa 之前需要很长时间。您可以在上面引用的示例代码行中看到这一点：

NSThread.detachNewThreadSelector_toTarget_withObject_("queryController", self, None)

这是编写Objective C行的Python方式：

[NSThread detachNewThreadSelector:@selector(queryController:) toTarget:self withObject:nil];

现在，重要的是要注意，这条线可以通过两种方式看到：(1) 作为 Objective C 的一行，或 (2) 作为 Cocoa 框架的调用。从语法上看，我们将其视为 (1)。通过认识到 NSThread 是一个提供一组方便特性的 Cocoa 框架，我们将其视为 (2)。在这种情况下，这个特殊的 Cocoa 框架让我们可以很容易地让一个对象在一个新线程上开始做某事。

但关键是：这里的 Cocoa 框架 (NSThread) 以一种与框架编写的语言明确相关的方式为我们提供了这种方便的服务。也就是说，NSThread 为我们提供了一个明确引用的特性“选择器”。实际上，选择器是关于 Objective C 工作原理的基本名称。

所以问题来了。 Cocoa 从根本上说是 Objective-C 的产物，它的创建者在构建它时考虑了 Objective C。我并不是说不可能将 Cocoa 特性的界面翻译成其他语言更自然的形式。只是一旦您更改 Cocoa 框架以停止引用“选择器”，它就不再是真正的 Cocoa 框架了。是翻译版本。一旦你开始走这条路，我猜事情会变得非常混乱。您正在努力跟上 Apple 更新 Cocoa 的步伐，也许您遇到了 Cocoa 的某些部分，这些部分只是不能很好地翻译成新的语言，无论如何。所以相反，像 PyObjC 这样的东西选择直接公开 Cocoa，以一种非常清晰和简单的相关性。正如他们在文档中所说：

为了在 Objective-C 消息和 Python 方法之间进行无损且明确的转换，Python 方法名称等价物只是将冒号替换为下划线的选择器。

当然，这有点难看，这确实意味着您需要了解一些有关 Objective-C 的知识，但那是因为替代方案，如果真的存在，不一定更好。

【讨论】：

【解决方案7】：

我对 Objective C 或 Cocoa 一无所知（但对 Python 了解很多），但我现在正在用 PyObjc 编写一个相当复杂的应用程序。我是怎么学的？我拿起Cocoa Programming for OSX 并使用 PyObjC 浏览了整本书（一个非常快速的过程）。只需忽略有关内存管理的任何内容，您就可以了。唯一需要注意的是，您有时必须使用 endSheetMethod 之类的装饰器（实际上我认为这是我唯一使用过的装饰器）：

@PyObjcTools.AppHelper.endSheetMethod
def alertEnded_code_context_(self, alert, choice, context):
    pass

【讨论】：

【解决方案8】：

这个答案不会很有帮助，但是作为开发人员，我讨厌做文档。这是一个开源项目，很难找到做文档的人。

【讨论】：

【解决方案9】：

Tom 说的都是真的。许多开源项目都有专门的开发人员，很少有人对文档感兴趣。球门柱每天都在变化这一事实无济于事，这意味着不仅要创建文档，还要维护文档。

【讨论】：