Advertise here




Advertise here

Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Tips on the Xcode documentation

Duncan CDuncan C Posts: 9,114Tutorial Authors, Registered Users @ @ @ @ @ @ @
edited August 2012 in iPhone SDK Tutorials
I get the impression that lots of readers of these forums don't know how to get the most out of the Xcode documentation.

There is a wealth of information in the Xcode docs, but there are some tricks to making the most of it.

First, the basics.

This tutorial is based on Xcode 4.3, the latest version of Xcode, but should be pretty accurate for all versions of Xcode >= 4.0. Xcode 4 uses a totally different user interface for help than Xcode 3.x (Ok, it uses a totally different interface for EVERYTHING.)

The Xcode documentation is in the organizer window. The fastest way to get to it is to select "Documentation and API reference" from the Xcode help menu. That brings the organizer window forward, selects the documentation tab, and selects the search tab inside the documentation tab. The keyboard shortcut for this is command-option question mark, which requires 4 fingers to press (since question mark is a shifted key.)

Once you have the help window up and the have selected search, it defaults to searching ALL the documentation sets that are installed.

This is bad for 2 reasons. First, it's really, really slow to search 3 versions of the iOS SDK and several versions of the Mac OS SDK. It can take 15 seconds or more to come back with results.

Worse, the Mac APIs are similar to, but different from, the iOS APIs. There are functions that work in Mac OS that don't work in iOS. Worse still, some of these APIs work if you build them for the simulator, but will not work on the device. that's because the simulator actually links against Mac OS frameworks. We got bit by this badly early in our efforts with iOS. My partner developed a very nice multi-file async download engine based on NSURLDownload, a file download framework. He tested it and gave it to me to integrate into a project I was working on. I got it integrated in the simulator, and everything seemed great. That was until I tried to run it on my phone. At that point it failed to link, because NSURLDownload is not supported in iOS It's Mac-only. It works on the simulator, but not on an actual iOS device. We had to do a heart-lung transplant on our download engine to make it work.


You can save yourself a lot of pain and suffering by not searching Mac frameworks, and only searching the iOS version you are working on. It's not obvious how to do that, however.

What you have to do is click on the little magnifying glass in the search box, and select "show find options". It looks like this:

http://img819.imageshack.us/img819/92/xcodeshowfindoptions.png

Once you do that, you want to select ONLY the doc-sets you care about. If you're building against the iOS 5.0 SDK, select that. If your deployment target is iOS 4.2, though, then you should only search in that doc set. That has a double benefit: It keeps you from finding new API calls that are only available in the latest OS, and it speeds up searching dramatically.

Here's what that looks like:

http://img853.imageshack.us/img853/6916/xcodedocsets.png

I also recommend selecting only C and Objective C under Languages. It's confusing to see C++, Java, and JavaScript versions of things if you're doing C and Objective C programming. (The languages setting is immediately below "Doc Sets" in the find options shown above.)

Another tip: The Xcode docs include links to lots of useful sample applications that show how to use different APIs. For example, if you search on "MKMapView", you'll see results under "Reference", "System Guides
, "Tool Guides", and "Sample Code"

The Sample Code group includes sample applications that use the MKMapView class. The "WorldCities" app, for example, creates a map of major world cities. Seaching on "CLLocationManager" returns a few of the same applications, plus applications like "LocateMe" that use the location manager but not map views.


One final tip: By default, Xcode 4.x only installs the most recent SDK versions and their documentation. You have to ask to download older SDK versions and the documentation to go with it.

To download older SDKS and documentation, go to the Xcode preferences window (command ",") and select the "Downloads" tab. Then select either "Documentation" or "Components"
and click the install buttons for any older SDK or documentation set versions that you need. Here's what that preferences screen looks like:

http://img845.imageshack.us/img845/117/xcodedownloadprefs.jpg
Post edited by Duncan C on
Regards,
Duncan C
WareTo

widehead.gif
Animated GIF created with Face Dancer, available for free in the app store.

I'm available for one-on-one help at CodeMentor

Replies

  • rdavis0521rdavis0521 Posts: 2New Users
    edited April 2012
    Great post. A minor comment and a question.

    1. comment - minor misspelling above seletx -> select?

    2. question - I thought in previous versions of Xcode, that I could select text defining a class, and there was a way to automatically open the documentation to the selected text. Right now I find myself copying, opening the docs window, and pasting into the search field. Do I remember incorrectly, or is there a way to do this?

    Thanks,
    Ray
  • DomeleDomele Posts: 2,991Registered Users @ @ @ @ @
    edited April 2012
    I think you option click.
    If you are looking for a quality developer, I'm your man. Give me a PM if you are interested.<br />
    <br />
    New app - See screenshots and details at <a href="http://www.globaclock.com"; target="_blank">www.globaclock.com</a>.<br />
    <br />
    If you want to
  • rdavis0521rdavis0521 Posts: 2New Users
    edited April 2012
    Domele wrote: »
    I think you option click.

    Thanks.
  • Duncan CDuncan C Posts: 9,114Tutorial Authors, Registered Users @ @ @ @ @ @ @
    edited April 2012
    Domele wrote: »
    I think you option click.

    Option single-click to bring up the "quick help" on that subject. Option double-click to open the Xcode docs for the topic on which you click.
    Regards,
    Duncan C
    WareTo

    widehead.gif
    Animated GIF created with Face Dancer, available for free in the app store.

    I'm available for one-on-one help at CodeMentor
  • Duncan CDuncan C Posts: 9,114Tutorial Authors, Registered Users @ @ @ @ @ @ @
    edited April 2012
    rdavis0521 wrote: »
    Great post. A minor comment and a question.

    1. comment - minor misspelling above seletx -> select?

    2. question - I thought in previous versions of Xcode, that I could select text defining a class, and there was a way to automatically open the documentation to the selected text. Right now I find myself copying, opening the docs window, and pasting into the search field. Do I remember incorrectly, or is there a way to do this?

    Thanks,
    Ray

    1. Thanks for pointing that out. I fixed it. I'm a fast typist, but not that accurate...


    2. See the other replies. (Option double-click on a word to look it up in the docs.)
    Regards,
    Duncan C
    WareTo

    widehead.gif
    Animated GIF created with Face Dancer, available for free in the app store.

    I'm available for one-on-one help at CodeMentor
  • guntarionguntarion Posts: 1New Users
    Thank you very much for the post, Duncan. This is very helpful to make the learning much more efficient! :-)
Sign In or Register to comment.