Re: Help understanding Apple's approach in documentation a little better.
On Aug 16, 2015, at 2:58 PM, Alex Zavatone wrote: > Would be REALLY nice if there was something visual that simply communicated > to you that they are not for public consumption. > > If I see it in the left pane of the debugger, and no visual indicators are > stating that it's restricted, It's telling us that it's available - unless we > spend the time to look up the internals for everything that's displayed in > the variables pane that exposes an object instanced from a framework class. > > I know it's too simplistic to assume that a color change would be enough and > appropriate to indicate to the programmer that "you can see there, but you > really don't have access to them", but SOME sort of treatment to the private > data would be really nice when displaying it, so that it's painfully obvious > to the developer that it's private freaking data. > > The developer should just have to look and instantly see that it's data > that's used behind the scenes and they can't play with it. > > If the debugger's variable pane exposes it, it's misleading if it doesn't > somehow indicate that it's not for the developer to access. > > At the least, it's confusing, because the docs say it's not supposed to be > there, yet there it is. No, both the headers and docs communicate what's public and what's not; the debugger's variable panel exposes all the properties, public or not. AFAIK there's no Obj-C ivar/property/method runtime attribute that marks that item as public or private, thus the debugger has no means of determining such. As has been mentioned previously, that useful (to you) private methods exist is an implementation detail subject to change in a future OS release. That may have been the best way to implement class functionality at the time, but since the method isn't in the public header or documentation, Apple is free to remove any or all of those private methods at any time or, more problematically, change the behavior of those methods. You can test for the former but not for the latter so you'd have to keep testing your app on every dot-release. Think about this from your own point of view: If you released a framework for developers to use, would you leave in all of your private methods forever even if you made radical internal changes, just so that you didn't break a developer who used one of them? ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help understanding Apple's approach in documentation a little better.
> > If the debugger's variable pane exposes it, it's misleading if it doesn't > somehow indicate that it's not for the developer to access. It is there for the developer to access -- when debugging. Might even be useful. I sometimes find the information useful when trying to understand how something is put together. But don’t use it for development. > At the least, it's confusing, because the docs say it's not supposed to be > there, yet there it is. The docs say no such thing or did I miss explicit statements that only documented methods and properties will ever exist? I think Ken is correct in saying "Their non-presence in the documentation and headers” is what shows them as private. Private is not that same as “not supposed to be there”. ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help understanding Apple's approach in documentation a little better.
On Aug 16, 2015, at 5:35 PM, Ken Thomases wrote: > On Aug 16, 2015, at 4:18 PM, Alex Zavatone wrote: > >> On Aug 16, 2015, at 4:49 PM, Ken Thomases wrote: >> >>> On Aug 16, 2015, at 3:09 PM, Alex Zavatone wrote: >>> Why isn't it in Apple's documentation for storyboards? >>> >>> Because these are private implementation details. They are subject to >>> change without notice. You can't rely on them in any shipping code. >> >> If they were private shouldn't there be a naming convention that states they >> are private? > > No, there's no naming convention for properties to indicate they are private. > >> If I look at an instance of a storyboard object in the Variables View in the >> Debugger, I can expand the object and they are all listed. > > And? You've already shown they are visible in the runtime's information > about the class. It's not surprising that the debugger also has access to > this information. > >> Is there some sort of naming or visual convention that communicates "you >> might be see these, but they're private and not for you to mess with"? > > No. > >> As soon as I saw them exposed by the runtime tool, and I saw that expanding >> the storyboard instance exposed them, I thought that the docs and header >> files were hiding information that was accessible. > > They are "accessible" through these (and probably other) mechanisms, but that > doesn't mean they are _appropriate_ to access. Working with the frameworks > or a library is always subject to a design contract. There are plenty of > times when it's _possible_ to do something but, if the design contract > doesn't specifically allow it, it's disallowed. Accessing private properties > is just a particular case of this general rule. > >> Is there anything that shows that they are private? > > Their non-presence in the documentation and headers. Would be REALLY nice if there was something visual that simply communicated to you that they are not for public consumption. If I see it in the left pane of the debugger, and no visual indicators are stating that it's restricted, It's telling us that it's available - unless we spend the time to look up the internals for everything that's displayed in the variables pane that exposes an object instanced from a framework class. I know it's too simplistic to assume that a color change would be enough and appropriate to indicate to the programmer that "you can see there, but you really don't have access to them", but SOME sort of treatment to the private data would be really nice when displaying it, so that it's painfully obvious to the developer that it's private freaking data. The developer should just have to look and instantly see that it's data that's used behind the scenes and they can't play with it. If the debugger's variable pane exposes it, it's misleading if it doesn't somehow indicate that it's not for the developer to access. At the least, it's confusing, because the docs say it's not supposed to be there, yet there it is. Fun. Thanks, Ken. Dearly appreciated. - Alex Zavatone ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help understanding Apple's approach in documentation a little better.
On Aug 16, 2015, at 4:18 PM, Alex Zavatone wrote: > On Aug 16, 2015, at 4:49 PM, Ken Thomases wrote: > >> On Aug 16, 2015, at 3:09 PM, Alex Zavatone wrote: >> >>> Why isn't it in Apple's documentation for storyboards? >> >> Because these are private implementation details. They are subject to >> change without notice. You can't rely on them in any shipping code. > > If they were private shouldn't there be a naming convention that states they > are private? No, there's no naming convention for properties to indicate they are private. > If I look at an instance of a storyboard object in the Variables View in the > Debugger, I can expand the object and they are all listed. And? You've already shown they are visible in the runtime's information about the class. It's not surprising that the debugger also has access to this information. > Is there some sort of naming or visual convention that communicates "you > might be see these, but they're private and not for you to mess with"? No. > As soon as I saw them exposed by the runtime tool, and I saw that expanding > the storyboard instance exposed them, I thought that the docs and header > files were hiding information that was accessible. They are "accessible" through these (and probably other) mechanisms, but that doesn't mean they are _appropriate_ to access. Working with the frameworks or a library is always subject to a design contract. There are plenty of times when it's _possible_ to do something but, if the design contract doesn't specifically allow it, it's disallowed. Accessing private properties is just a particular case of this general rule. > Is there anything that shows that they are private? Their non-presence in the documentation and headers. Regards, Ken ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help understanding Apple's approach in documentation a little better.
> On 16 Aug 2015, at 22:18, Alex Zavatone wrote: > > > On Aug 16, 2015, at 4:49 PM, Ken Thomases wrote: > >> On Aug 16, 2015, at 3:09 PM, Alex Zavatone wrote: >> >>> So, I look at UIStoryboard.h and the docs and see that there are 3 methods. >>> No properties. >> >>> And in using it, I find out that in addition to the 3 methods within >>> UIStoryboard.h, inside a an instance of UIStoryboard, there are a bunch of >>> properties that appear to be stupidly useful. >>> >>> Like so: >>> designatedEntryPointIdentifier >>> identifierToNibNameMap >>> storyboardFileName >>> name >>> bundle >> >>> This is really great. I can see if any of my view controllers' scenes' >>> identifiers are misspelled, I can see what Cocoa's using and verify where >>> or if I screwed up somewhere. >>> >>> This is really useful information. >>> >>> Why isn't it in Apple's documentation for storyboards? >> >> Because these are private implementation details. They are subject to >> change without notice. You can't rely on them in any shipping code. > > If they were private shouldn't there be a naming convention that states they > are private? > > If I look at an instance of a storyboard object in the Variables View in the > Debugger, I can expand the object and they are all listed. > > Is there some sort of naming or visual convention that communicates "you > might be see these, but they're private and not for you to mess with"? > > As soon as I saw them exposed by the runtime tool, and I saw that expanding > the storyboard instance exposed them, I thought that the docs and header > files were hiding information that was accessible. > > Is there anything that shows that they are private? Yes, whether they’re in the header or not! And even then, any instance variables that appear in headers are almost always marked as private there, either using @private or a comment, depending on the age of the code. ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help understanding Apple's approach in documentation a little better.
On Aug 16, 2015, at 4:49 PM, Ken Thomases wrote: > On Aug 16, 2015, at 3:09 PM, Alex Zavatone wrote: > >> So, I look at UIStoryboard.h and the docs and see that there are 3 methods. >> No properties. > >> And in using it, I find out that in addition to the 3 methods within >> UIStoryboard.h, inside a an instance of UIStoryboard, there are a bunch of >> properties that appear to be stupidly useful. >> >> Like so: >> designatedEntryPointIdentifier >> identifierToNibNameMap >> storyboardFileName >> name >> bundle > >> This is really great. I can see if any of my view controllers' scenes' >> identifiers are misspelled, I can see what Cocoa's using and verify where or >> if I screwed up somewhere. >> >> This is really useful information. >> >> Why isn't it in Apple's documentation for storyboards? > > Because these are private implementation details. They are subject to change > without notice. You can't rely on them in any shipping code. If they were private shouldn't there be a naming convention that states they are private? If I look at an instance of a storyboard object in the Variables View in the Debugger, I can expand the object and they are all listed. Is there some sort of naming or visual convention that communicates "you might be see these, but they're private and not for you to mess with"? As soon as I saw them exposed by the runtime tool, and I saw that expanding the storyboard instance exposed them, I thought that the docs and header files were hiding information that was accessible. Is there anything that shows that they are private? >> Is it in Apple's documentation for storyboards but I don't know where to >> look? >> >> If it is, what concept am I missing about understanding Apple's way of >> documenting their classes that would help me better understand how to look >> and where to look when researching? > > The concept you're missing is the existence of private implementation details. > >> I never would have known about these unlisted (yet accessible and valuable) >> properties unless I used a special tool to show what's in each object that >> derives from NSObject. > > Because you weren't supposed to know about them. That's why they're unlisted. > >> That feels really really, um, deceiving (for lack of a better term). > > The fact that classes can have private details is deceiving? Or the fact > that Objective-C's run time allows introspection that reveals them? > >> Am I doing it wrong? > > Yes. If it's not in the documentation or headers, you shouldn't be using it > (except for recreational/educational exploration or debugging). > Yeah, in this case that leads to other questions of, "well, how can I get access to that functionality those private variables expose, because it's damn useful", but that's for another day. Thanks Ken. ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help understanding Apple's approach in documentation a little better.
On Aug 16, 2015, at 3:09 PM, Alex Zavatone wrote: > So, I look at UIStoryboard.h and the docs and see that there are 3 methods. > No properties. > And in using it, I find out that in addition to the 3 methods within > UIStoryboard.h, inside a an instance of UIStoryboard, there are a bunch of > properties that appear to be stupidly useful. > > Like so: > designatedEntryPointIdentifier > identifierToNibNameMap > storyboardFileName > name > bundle > This is really great. I can see if any of my view controllers' scenes' > identifiers are misspelled, I can see what Cocoa's using and verify where or > if I screwed up somewhere. > > This is really useful information. > > Why isn't it in Apple's documentation for storyboards? Because these are private implementation details. They are subject to change without notice. You can't rely on them in any shipping code. > Is it in Apple's documentation for storyboards but I don't know where to look? > > If it is, what concept am I missing about understanding Apple's way of > documenting their classes that would help me better understand how to look > and where to look when researching? The concept you're missing is the existence of private implementation details. > I never would have known about these unlisted (yet accessible and valuable) > properties unless I used a special tool to show what's in each object that > derives from NSObject. Because you weren't supposed to know about them. That's why they're unlisted. > That feels really really, um, deceiving (for lack of a better term). The fact that classes can have private details is deceiving? Or the fact that Objective-C's run time allows introspection that reveals them? > Am I doing it wrong? Yes. If it's not in the documentation or headers, you shouldn't be using it (except for recreational/educational exploration or debugging). Regards, Ken ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Help understanding Apple's approach in documentation a little better.
I'm currently writing a storyboard inspector for helping to create more modular
app pieces in iOS (8)
The idea is if you have enough functionality that is self contained enough, it
should (I hope) be organizationally more efficient to create a storyboard that
handles the desired functionality and can be launched and disposed of as needed.
Naturally, I'm relying on Apple's docs to help me build this and access
UIStoryboard properties, methods and set up my little methods to manage this
process.
So, I look at UIStoryboard.h and the docs and see that there are 3 methods. No
properties.
OK.
That seems sparse.
While building this out and finding out where I screw up with UIStoryboard, I
am using the little category to extend NSObject that dumps all the properties,
property classes and where appropriate, the property values of any object
instance that originates.
And in using it, I find out that in addition to the 3 methods within
UIStoryboard.h, inside a an instance of UIStoryboard, there are a bunch of
properties that appear to be stupidly useful.
Like so:
designatedEntryPointIdentifier
identifierToNibNameMap
storyboardFileName
name
bundle
That seems sparse.
In my case, we have these values which appear in an instance of the
ForgotPassword module I'm creating.
[UIStoryboard {identifierToUINibMap: NSMutableDictionary = (null);
designatedEntryPointIdentifier: NSString = (null);
identifierToNibNameMap: NSDictionary = {
"Forgot Password View Controller" = "Forgot Password View Controller";
"Nav Controller" = "Nav Controller";
"Password Has Been Changed View Controller" = "Password Has Been Changed
View Controller";
};
storyboardFileName: NSString = ForgotPassword.storyboardc;
name: NSString = ForgotPassword;
bundle: NSBundle = NSBundle
(loaded);
}]
This is really great. I can see if any of my view controllers' scenes'
identifiers are misspelled, I can see what Cocoa's using and verify where or if
I screwed up somewhere.
This is really useful information.
Why isn't it in Apple's documentation for storyboards?
Is it in Apple's documentation for storyboards but I don't know where to look?
If it is, what concept am I missing about understanding Apple's way of
documenting their classes that would help me better understand how to look and
where to look when researching?
I find it really, really odd that the docs go to great extent to try and
present the information they have in an educational and seemingly complete
manner and then find that "oh, we didn't bother to tell you about this stuff
and we're not going to make it easy to find it at all.
See, Apple's docs RARELY say "oh, and you might also want to look here if
you're looking for XXX about YYY".
They give you the impression that "these are complete and that's all the
information you should need to know about the subject. We're giving you all
that you need."
Well, identifierToNibNameMap tells me where/if I screwed up my identifier names
for scenes for my view controllers.
I never would have known about these unlisted (yet accessible and valuable)
properties unless I used a special tool to show what's in each object that
derives from NSObject. That feels really really, um, deceiving (for lack of a
better term).
Am I doing it wrong?
Thanks,
Alex Zavatone
___
Cocoa-dev mailing list (Cocoa-dev@lists.apple.com)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com
This email sent to arch...@mail-archive.com
