Wangling

KVO(Key-Value Observing) is a very nice programming facility from Apple. Working together with KVC(Key-Value Coding), it makes the life of Apple developers a lot easier and happier.

However, I recently found some annoying problems of KVO while building some reusable programming components ^(I’ll open source as much as possible when ready.)$ for Voodo and future iOS projects.

Observers can not be queried

Observers are stored in dictionaries ^(See NSKeyValueObserving protocol’s observationInfo.)$, so it should be very easy to query whether an object A is a registered observer of object B. But one can’t do that.

Unregistering an unregistered observer throws exception

One can not query whether A is an observer of B in the first place, and can neither try to unregister it from B when one wants to ensure that A is unregistered from B. It is just ridiculous! And why is removing a nonexistent observer so fatal while removing a nonexistent entry from a collection is reasonably ignored? ^(See NSMutableArray’s removeObject: and NSMutableDictionary’s removeObjectForKey:)$

Observers/observees don’t auto-dissolve the KVO relationship in dealloc

It can be easily done in KVO framework code since it already has the data structure keeping the observer-observee relationship information, and is very reasonable things to do – when any part of a relationship is gone the relationship is ended. Without the auto-unregistration, developers’ responsibility is unnecessarily heavier. In fact, it is no easy work in cases where observers outlive observees, because an observee needs to notify its observers of its death so the observers can detach themselves from the dying observee. ^(Normally it is the observers that are doing the KVO relationship management and it is the job of whoever did the connection to do the disconnection, but vice versa)$

All in all

KVO leaves some extra, tedious, and burdensome relationship management work to us while it could be easily and efficiently done at the root of itself. ^(Well, as Appler eskimo1 said in devforums, it is harder than one might think because KVO needs to be both thread safe and GC clean, and must be careful to not impact the performance of code that isn’t using it.)$

The KVO relationship management is especially stressful for observers watching many dynamic observees which is not unusual for generic components – UINavigationController and UITabBarController both manage a dynamic group of UIViewControllers and may observe some properties of them. It is even worse in my component because not only the observee but also the observed properties of them are dynamic. May Apple save me (and you?).

Documentation set generation tool in Xcode to generate documentation sets in the style of Apple Developer Documentation is necessary for a prosperous Apple developer community. The current HeaderDoc and Doxygen are both far from Apple standard.

HeaderDoc is obviously not favored by developers. Doxygen is better and even officially advocated by Apple, but still tedious to use and just can’t generate Apple standard documentations(see a nice example here). Doxyclean is very helpful in converting Doxygen output to resemble Apple Developer Documentation, but seems not capable to generate Xcode Documentation Sets. Following the work of Doxyclean, appledoc supplements some missing features like Xcode Documentation Set generation.

To sum up, there are several third-party tools doing the work that should be better done by Apple in Apple way. Even though they can do their best to generate very Apple like documentations, they can not offer the smooth integration in Xcode that is otherwise possible if it is done by Apple.

So, I’ve posted a bug report(Problem ID: 8193210) to request such a Documentation Set generation tool. If you also want it, please go to duplicate a bug report with following content:

I vote for bug report ‘8193210′.

Summary:
Documentation set generation tool in Xcode to generate documentation set in the style of Apple Developer Documentation is necessary for a prosperous Apple developer community. The current HeaderDoc and doxygen are both far from the Apple standard.

Steps to Reproduce:

Expected Results:

Actual Results:

Regression:

Notes:

Read this article to learn why and how to vote for a bug report. ^(Surely I’ve voted this “international promo codes” bug report since I’m from China.)$

刚完成了 Voodo 2 的开发，正在写用户手册，其中用到不少截图。

对 app 自身的截图，用真机 + Xcode 就能完美解决，但是对截图做注释就需额外的工具来完成。

一说到对图片进行操作，大家容易先想到 Photoshop, Illustrator，OmniGraffle 等重器，轻一点的也是 Acorn，Pixelmator 等。

这些专业的图片编辑软件确实强大，有些功能只有它们能提供。比如，我试了一圈，最终发现还是 Illustrator 里的 gradient 强大，是唯一一个直接支持 ellipse gradient 效果的，于是在对截图做聚光效果时都是用的 Illustrator。

既然我在对 Voodo 2 做截图时用的是 Xcode，后续工作是图片注释，为什么还需要截屏软件呢？

这是因为，其实大多截屏软件都自带注释功能，足以应付绝大多数需求；而且因为 Voodo 有同步 Google Calendar 的功能，我需要对 Google Calendar 上的操作进行一些截图。

下面就我用过的一些截屏软件做一个简单的比较（排名无明显先后）：

Snagit

Snagit 不愧是老牌领头羊，beta 就已经多方面超越其他先入场的小弟了，操作的灵活性，注释工具都是最好的。beta 版免费使用，很爽。

没有单独的 Full Screen Capture，那是因为根本不需要，人家的 All-in-One Capture 太帅了，自动识别 Full Screen，Window，甚至 Region in Window，还有 Capture Scrolling Area 能对需要滚动才能看全的页面做完整的截图。

Share 功能尚未成型，暂时只内嵌了 Email 功能。相信正式版肯定会有完善的 Share 功能，看看 TechSmith 的其他软件就知道了，何况人家还拥有自己的专业多媒体资源分享网站 Screencast.com。

Snapz Pro X

Snapz Pro X 没有注释功能，也不带 Share。但就截图的一个“截”字来说，Snapz Pro X 确实可算是最强悍的，算是名副其实。看一个它特有的截图功能：

其实把它放到这里并不完全合适，因为 Snapz Pro X 同时还是强大的 Screencast 录制软件。我购买它就是为了给 Voodo 录制 demo 及 promo video，配合着 iMovie 做的后期制作，一般的效果都能达到。

Skitch

Skitch 的 UI 设计相当独特，类似一个相框，上传分享特别方便（skitch.com，flickr，Mobile Me 等一应俱全），截图质量和注释工具都不错，而且免费。性价比最高，估计是目前最普及的截图软件。我一般都通过 Skitch 上传到 skitch.com 秀图给别人看。

LittleSnapper

LittleSnapper 可能是最眼熟的一个名字。软件本身 UI 也算清爽，功能也算齐全，支持多种 Share 方式，包括 flickr，但上手感觉不利索，不像名字取的那样 little。

我特别不喜欢它的截图方式，定位不如其他三个的十字交叉线来的方便：

不过，LittleSnapper 也有亮点：1) 组织管理功能比较强大，适合剪贴报爱好者；2）强大的网页截图功能，它自带 HTML 解析器，能定位到 Element，适合网页设计者。

系统自带

最后，不得不说，其实 Mac 系统自带的截图功能对付日常工作已经绰绰有余，截图质量更是没得说。再配上 Preview 做点简单的注释，80%的活都能应付。

As a Mac user and developer, I’ve been looking for good alternatives to DropBox for on-line backup and sync, since I found myself dragging all kinds of configure files and directories into DropBox and then linking to them from their original paths. This move-and-link scheme is just too awkward to bear as more and more scattered files and directories are involved.

Today, I stumbled upon SugarSync which seems very promising. The most outstanding advantage of SugarSync over DropBox is its flexibility to backup/sync any folders. You can see the detailed comparison between SugarSync and other prominent competitors here.

However, just before I set out to download SugarSync Manager 1.6.2 for Mac (Beta), I glimpsed the Known Issues ^(The more software you use, especially the more software you develop, the more wary of software you are.)$, and one of them scared the pants off me. It said:

If you are using a mac that has been formatted with a case-sensitive filesystem instead of the default case-insensitive filesystem, SugarSync may not function properly due to incorrect case of paths.

I am definitely one of those implied idiots that formatted their effeminate Macs with Case-Sensitive filesystems just to show more masculine. Fine, in fact, I am a 6-year-old Linux user. Whatsoever, what on earth makes you developers resist case-sensitivity so much that you prefer to turn down your peer Unix developers ^(I don’t think Windows users care about case-sensitivity because they never have one, and aren’t all Unix (before Mac OS X) users developers?)$? Are you as arrogant as Adobe?

I am also a coward who dare not to take a risk. What do you mean by “may not function properly“? ^(Maybe, by “may not” instead of “will not”, they mean it works well even on case-sensitive filesystems only if there are not any files or directories distinguishable only by case?)$ Will it damage my original data, or just refuse to backup them? And why don’t you just say “SugarSync does not support case-sensitive filesystems (right now), so do not use SugarSync on them.”?

What if I took the risk and lost my data? So then you can disclaim “We have warned you that it may not function properly. You made the decision. You take the responsibility.”?

I think there are some basic moral code that a properly functioning vendor should follow:

• For cases where your product function perfectly, proudly announce them and dutifully guarantee them.
• For cases where your product does not function perfectly, describe the deficiencies clearly.
• For cases you are not sure, confess candidly that even you are not sure and advise users against using it in those cases.
• Never make any cunning disclaimers, because, you see, weasel words “may not function properly“, or even hurt your prospects.

Hi, here is the first cup of Cocoa from Cocoa Nut. And it is Yummy.

I just can’t wait for the icon from J any longer, so let a naked Yummy debut.

What is Yummy then?

Of course, Cocoa is yummy ; and Yummy is made with Cocoa.

Seriously, Yummy is the best Delicious client on Mac. It judiciously does the jobs Delicious users want to do, and does them well, and nothing else.

You can get more info of and download it here.

Since it is the first Cocoa post, it certainly deserves some additional tips, and here is one:

When you decide to bookmark current web page in Safari, you can press Cmd-L to select the current URL in the address bar, then press Shift-Cmd-M(or choose `Bookmark in Delicious’ in Services menu) to call out Yummy.