<story><title>The State of Apple&apos;s Developer Documentation</title><url>https://mjtsai.com/blog/2019/05/20/the-state-of-apples-developer-documentation/</url></story><parent_chain><item><author>gnachman</author><text>Some personal favorites, culled by searching my source code for swear words:&lt;p&gt;NSTitleBarAccessoryViewController lacked documentation from the time it was introduced in macOS 10.10 until recently (perhaps Mojave? That&amp;#x27;s when I first found it). There was literally nothing except the header file and the announcment in the release notes for the OS. It was also full of bugs that rendered it unusable for my application.&lt;p&gt;Overriding -scrollWheel: has all kinds of nonsense side-effects. These are only documented in release notes. Scroll wheels in general are way more complex than you&amp;#x27;d imagine. If it weren&amp;#x27;t for Chrome&amp;#x27;s open source Mac code, it would be a complete mystery. See the investigation here (search for &amp;quot;of mice and men&amp;quot;) for what Apple should have documented: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;chromium.googlesource.com&amp;#x2F;chromium&amp;#x2F;blink&amp;#x2F;+&amp;#x2F;d40e271ac1613cea1a24eac3cca6efe173cd0696&amp;#x2F;Source&amp;#x2F;WebKit&amp;#x2F;chromium&amp;#x2F;src&amp;#x2F;mac&amp;#x2F;WebInputEventFactory.mm&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;chromium.googlesource.com&amp;#x2F;chromium&amp;#x2F;blink&amp;#x2F;+&amp;#x2F;d40e271ac...&lt;/a&gt;&lt;p&gt;Passing a constant buffer to a fragment shader will cause it to be truncated at 64k on some graphics drivers. Not a bug, just an undocumented limitation. Doesn&amp;#x27;t happen on my computer. That was fun to figure out.&lt;p&gt;NSMapTable with weak keys and strong value leaks the values, according to an archived document. The main docs say nothing on the topic.&lt;p&gt;If you&amp;#x27;d like to know why an exception was thrown, you have to print the value of the proper CPU register. On x86-64 it&amp;#x27;s $rax. As far as I know this is an oral tradition, passed down from senior developer to junior developer.&lt;p&gt;If you want a daemon to survive the user logging out and logging in, you have to use a barely-documented function (bootstrap_parent) which is only mentioned in a now-archived tech note.</text></item></parent_chain><comment><author>pcwalton</author><text>&amp;gt; Passing a constant buffer to a fragment shader will cause it to be truncated at 64k on some graphics drivers. Not a bug, just an undocumented limitation. Doesn&amp;#x27;t happen on my computer. That was fun to figure out.&lt;p&gt;That doesn&amp;#x27;t even begin to scratch the surface of OpenGL bugs on Apple devices. Many more are documented here: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;servo&amp;#x2F;webrender&amp;#x2F;wiki&amp;#x2F;Driver-issues&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;servo&amp;#x2F;webrender&amp;#x2F;wiki&amp;#x2F;Driver-issues&lt;/a&gt;</text></comment>
<story><title>The State of Apple&apos;s Developer Documentation</title><url>https://mjtsai.com/blog/2019/05/20/the-state-of-apples-developer-documentation/</url></story><parent_chain><item><author>gnachman</author><text>Some personal favorites, culled by searching my source code for swear words:&lt;p&gt;NSTitleBarAccessoryViewController lacked documentation from the time it was introduced in macOS 10.10 until recently (perhaps Mojave? That&amp;#x27;s when I first found it). There was literally nothing except the header file and the announcment in the release notes for the OS. It was also full of bugs that rendered it unusable for my application.&lt;p&gt;Overriding -scrollWheel: has all kinds of nonsense side-effects. These are only documented in release notes. Scroll wheels in general are way more complex than you&amp;#x27;d imagine. If it weren&amp;#x27;t for Chrome&amp;#x27;s open source Mac code, it would be a complete mystery. See the investigation here (search for &amp;quot;of mice and men&amp;quot;) for what Apple should have documented: &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;chromium.googlesource.com&amp;#x2F;chromium&amp;#x2F;blink&amp;#x2F;+&amp;#x2F;d40e271ac1613cea1a24eac3cca6efe173cd0696&amp;#x2F;Source&amp;#x2F;WebKit&amp;#x2F;chromium&amp;#x2F;src&amp;#x2F;mac&amp;#x2F;WebInputEventFactory.mm&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;chromium.googlesource.com&amp;#x2F;chromium&amp;#x2F;blink&amp;#x2F;+&amp;#x2F;d40e271ac...&lt;/a&gt;&lt;p&gt;Passing a constant buffer to a fragment shader will cause it to be truncated at 64k on some graphics drivers. Not a bug, just an undocumented limitation. Doesn&amp;#x27;t happen on my computer. That was fun to figure out.&lt;p&gt;NSMapTable with weak keys and strong value leaks the values, according to an archived document. The main docs say nothing on the topic.&lt;p&gt;If you&amp;#x27;d like to know why an exception was thrown, you have to print the value of the proper CPU register. On x86-64 it&amp;#x27;s $rax. As far as I know this is an oral tradition, passed down from senior developer to junior developer.&lt;p&gt;If you want a daemon to survive the user logging out and logging in, you have to use a barely-documented function (bootstrap_parent) which is only mentioned in a now-archived tech note.</text></item></parent_chain><comment><author>Klonoar</author><text>Yup! I mentioned in another comment here, but overriding scrollWheel can completely kill smooth scrolling and is only mentioned in some release notes.&lt;p&gt;It&amp;#x27;s crazy.</text></comment>