6 ms·

Some personal favorites, culled by searching my source code for swear words: NSTitleBarAccessoryViewController lacked documentation from the time it was introd

Some personal favorites, culled by searching my source code for swear words: NSTitleBarAccessoryViewController lacked documentation from the time it was introduced in macOS 10.10 until recently (perhaps Mojave? That'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. 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'd imagine. If it weren't for Chrome's open source Mac code, it would be a complete mystery. See the investigation here (search for "of mice and men") for what Apple should have documented: https://chromium.googlesource.com/chromium/blink/+/d40e271ac1613cea1a24eac3cca6efe173cd0696/Source/WebKit/chromium/src/mac/WebInputEventFactory.mm https://chromium.googlesource.com/chromium/blink/+/d40e271ac... 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't happen on my computer. That was fun to figure out. NSMapTable with weak keys and strong value leaks the values, according to an archived document. The main docs say nothing on the topic. If you'd like to know why an exception was thrown, you have to print the value of the proper CPU register. On x86-64 it's $rax. As far as I know this is an oral tradition, passed down from senior developer to junior developer. 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.

Klonoar 7y ago
Yup! I mentioned in another comment here, but overriding scrollWheel can completely kill smooth scrolling and is only mentioned in some release notes. It's crazy.
- helge5 7y ago
  It is mentioned a few times, but never w/ any reference or explanation :-) Could someone please provide some pointers on this?
  - Klonoar 7y ago
    So, I know they were in the 10.9 release notes, because 10.9 was where smooth scrolling was introduced. However... as is typical, I cannot even seem to find those release notes now? Someone appears to have mirror them in a gist, so open this (https://gist.github.com/zwaldowski/8710fddc8b0b39d2c152 https://gist.github.com/zwaldowski/8710fddc8b0b39d2c152) and ctrl+f for "Responsive Scrolling". > Do not override -scrollWheel: in an NSScrollView, NSClipView subclass, or in the document view.
saagarjha 7y ago
> If you'd like to know why an exception was thrown, you have to print the value of the proper CPU register. On x86-64 it's $rax. As far as I know this is an oral tradition, passed down from senior developer to junior developer. This varies based on the calling convention and signature of the the method that the exception handler puts a breakpoint on. With objc_exception_throw on x86_64 the value should be in $rdi ($arg1) in LLDB. > 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. It's also mentioned in Mac OS X Internals: A Systems Approach, FWIW.
- aaronbrethorst 7y ago
  It’s always a good sign when the document that explains a piece of functionality no longer bears the same name as the operating system it purports to document.
  - tinus_hn 7y ago
    That’s kind of hard to avoid if it’s a physical book and the subject changes names.
    - oblio 7y ago
      I think his point is that it should be documented online, in an ever-green knowledge base...
  - userbinator 7y ago
    This comment nicely sums up one of the things that's wrong with the Apple ecosystem --- apparently, whatever backwards-compatibility Apple does manage to have gets dismissed by developers because "it's old". ...and then they wonder why they can't find the old docs that actually have what they need. Apple thinks the developers don't care, and vice-versa. It's a cycle of negative feedback. On most other platforms, the assumption is that things will not change between versions, and changes are explicitly mentioned and documented when they do occur, but Apple and its developers seem to have the exact opposite mentality.
pcwalton 7y ago
> 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't happen on my computer. That was fun to figure out. That doesn't even begin to scratch the surface of OpenGL bugs on Apple devices. Many more are documented here: https://github.com/servo/webrender/wiki/Driver-issues https://github.com/servo/webrender/wiki/Driver-issues
- saagarjha 7y ago
  OpenGL is technically deprecated on Apple's platforms, so you're not likely to get much support either…
bronxbomber92 7y ago
If the Metal debug layer doesn’t warn you, then it is a bug (either in the driver or in the debug layer depending on the intended behaviour).
saywhat2 7y ago
> If you'd like to know why an exception was thrown, you have to print the value of the proper CPU register. I'm not sure what you mean. To see why an exception was thrown you can call [-NSException reason][0]. If you're stopped in your catch block in the debugger, it's as simple as typing: > call (NSString*)[e reason] Assuming your exception is named "e". [0]https://developer.apple.com/documentation/foundation/nsexception/1415537-reason?language=objc https://developer.apple.com/documentation/foundation/nsexcep...
kccqzy 7y ago
I read the "Of Mice and Men" investigation. It was a good read. But I guess the kicker is that this code is in fact written by Apple for WebKit long before Google forked Blink (do a git blame; and see notes that "if you linked on Tiger or above"). I would've thought for all the vague public-facing documentation, Apple's internal documentation must be better. I guess that's not so.

Klonoar 7y ago

Yup! I mentioned in another comment here, but overriding scrollWheel can completely kill smooth scrolling and is only mentioned in some release notes. It's crazy.

helge5 7y ago
It is mentioned a few times, but never w/ any reference or explanation :-) Could someone please provide some pointers on this?
- Klonoar 7y ago
  So, I know they were in the 10.9 release notes, because 10.9 was where smooth scrolling was introduced. However... as is typical, I cannot even seem to find those release notes now? Someone appears to have mirror them in a gist, so open this (https://gist.github.com/zwaldowski/8710fddc8b0b39d2c152 https://gist.github.com/zwaldowski/8710fddc8b0b39d2c152) and ctrl+f for "Responsive Scrolling". > Do not override -scrollWheel: in an NSScrollView, NSClipView subclass, or in the document view.

saagarjha 7y ago

> If you'd like to know why an exception was thrown, you have to print the value of the proper CPU register. On x86-64 it's $rax. As far as I know this is an oral tradition, passed down from senior developer to junior developer. This varies based on the calling convention and signature of the the method that the exception handler puts a breakpoint on. With objc_exception_throw on x86_64 the value should be in $rdi ($arg1) in LLDB. > 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. It's also mentioned in Mac OS X Internals: A Systems Approach, FWIW.

aaronbrethorst 7y ago
It’s always a good sign when the document that explains a piece of functionality no longer bears the same name as the operating system it purports to document.
- tinus_hn 7y ago
  That’s kind of hard to avoid if it’s a physical book and the subject changes names.
  - oblio 7y ago
    I think his point is that it should be documented online, in an ever-green knowledge base...
- userbinator 7y ago
  This comment nicely sums up one of the things that's wrong with the Apple ecosystem --- apparently, whatever backwards-compatibility Apple does manage to have gets dismissed by developers because "it's old". ...and then they wonder why they can't find the old docs that actually have what they need. Apple thinks the developers don't care, and vice-versa. It's a cycle of negative feedback. On most other platforms, the assumption is that things will not change between versions, and changes are explicitly mentioned and documented when they do occur, but Apple and its developers seem to have the exact opposite mentality.

pcwalton 7y ago

> 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't happen on my computer. That was fun to figure out. That doesn't even begin to scratch the surface of OpenGL bugs on Apple devices. Many more are documented here: https://github.com/servo/webrender/wiki/Driver-issues https://github.com/servo/webrender/wiki/Driver-issues

saagarjha 7y ago
OpenGL is technically deprecated on Apple's platforms, so you're not likely to get much support either…

bronxbomber92 7y ago

If the Metal debug layer doesn’t warn you, then it is a bug (either in the driver or in the debug layer depending on the intended behaviour).

saywhat2 7y ago

> If you'd like to know why an exception was thrown, you have to print the value of the proper CPU register. I'm not sure what you mean. To see why an exception was thrown you can call [-NSException reason][0]. If you're stopped in your catch block in the debugger, it's as simple as typing: > call (NSString*)[e reason] Assuming your exception is named "e". [0]https://developer.apple.com/documentation/foundation/nsexception/1415537-reason?language=objc https://developer.apple.com/documentation/foundation/nsexcep...

kccqzy 7y ago

I read the "Of Mice and Men" investigation. It was a good read. But I guess the kicker is that this code is in fact written by Apple for WebKit long before Google forked Blink (do a git blame; and see notes that "if you linked on Tiger or above"). I would've thought for all the vague public-facing documentation, Apple's internal documentation must be better. I guess that's not so.