Annoying documentation issue

Question

Created Nov ’17

Replies 5

Boosts 1

Views 1.4k

Participants 5

I've been using Xcode and Objective-C for years, and rely heavily on the built-in documentation, which is for the most part good.

There's an issue that's always bothered me. Today I was looking up a function called class_getName. I found its documentation page, and was also able to navigate to the page showing the overview of the runtime system, all of which is fine.

When I typed "class_getName" into my program, the compiler immediately flagged it as an unknown symbol.

I knew I probably had to include a header, but none of the documentation pages I looked at mentioned the name of the header file. I had to end up searching the internet for examples until I hit one that showed <objc/runtime.h> being imported.

Why isn't this very small, simple and extremely useful bit of information included in the documentation?

Frank

Boost

Answer 1

QuinceyMorris OP

Nov ’17

What's going on is a bit weird. In the past, the documentation used to say explicitly what you needed to #import for all of Apple's public frameworks. As you say, this information isn't present any more in the obvious places. However, I don't think it's a mistake. Instead, it looks like a consequence of the "module-ification" of the frameworks. If you look at this page, for example:

https://developer.apple.com/documentation/objectivec?language=objc

you'll see that the first heading line identifies this as documentation for a framework, and the second heading line identifies this framework as "Objective-C". This information suggests that the correct way to import this framework is like this:

     @import Objective-C;

because, these days, @import is preferred over #import for frameworks where possible. When I tried this @import, I found that the module is actually called "ObjectiveC", but at least Xcode gave it to me via autocomplete.

All of this is to say, you were looking for a harder answer than the actual, new, easy answer. Still, it's worth a bug report, for at least these reasons:

1. The documentation doesn't really say anywhere to use @import.

2. The module name isn't correct in this case.

3. In cases where you can't use modules, the equivalent #import isn't obvious because it's no longer documented.

0

Answer 2

jbicklebb OP

May ’23

Still a problem five years later. For example, https://developer.apple.com/documentation/os/os_log does not state that which headers I need to include. In case you're wondering, it's "os/log.h".

0

Answer 3

DTS Engineer OP

Apple

May ’23

Quite.

Please do file a bug about this. Our doc story has changed quite a bit in the last few years — Hello DocC! — and that yields more opportunity for fixes like this.

Please post your bug number, just for the record.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

0

Answer 4

endecotp OP

May ’23

Please do file a bug about this.

Interesting, I had assumed this was a deliberate change. You think not?

I've just filed FB12169839.

0

Answer 5

DTS Engineer OP

Apple

May ’23

Thanks for filing FB12169839.

I had assumed this was a deliberate change.

A lot of the time it doesn’t matter whether the change was deliberate. If it’s annoying, it’s worth filing a bug about, requesting that we improve it.

I took a quick look at your bug, just to confirm that it’s landed in the right place, and, amusingly, the engineer who routed it added a comment that they agree with you. That doesn’t mean it’s going to change, of course, but you’re certainly not alone.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

0