Digging into Documentation

How did we know that an AVPlayer class exists, and that it can play an audio stream? Well, for now, your authors are happy to steer you in the right direction, but eventually you’ll want to find features and functionality on your own, so let’s see how that’s done.

The documentation for the iOS SDK is available within Xcode itself, in a handy documentation viewer. Use the menu item Window > Documentation and API Reference (⇧⌘0) to show it.

When opened for the first time, the documentation viewer shows a two-pane window that lists three languages in the left pane—Swift, Objective-C, and JavaScript—and has an empty right pane. At the top, there’s a toolbar with forward and back buttons, two other buttons, and a search field.

The two buttons hide and show two panes on the left side. The leftmost one, disabled by default, shows or hides the list of languages. This is actually the top-level Navigator for all documentation. Each language has a disclosure indicator (the triangle spinner) that lets us drill down for more information. Expand the Swift topic to see what it has to offer.

Under Swift, we find section headers like App Frameworks, App Services, and Developer Tools, and under each of these are topics that have disclosure triangles of their own. If we scroll down to Media and Web, we find an entry for AV Foundation, which you’ll recall was something we used for creating our web radio player. Expand this topic and we find subheadings for classes, protocols, references, and more.

Under Classes, find AVPlayer and select it. This brings up the documentation for the class we used to play our web radio stream. We can scroll through this page or expand its disclosure triangle to see its topics in the Navigator: Creating a Player, Managing Playback, and more, as seen in the figure.

If we look under Creating a Player, we find init(url:). Click it to navigate to a page for this initializer. The page shows the syntax for creating an AVPlayer from a URL, describes the parameters and return value, and has a discussion section with further notes on its usage. All the documentation pages will use this general structure.

So now we know that to create an AVPlayer to play our audio, we just need to create a URL object and call AVPlayer(url: myURL). And if we look in the Navigator on the left, under Managing Playback we’ll find the play method that started playing our stream.

Searching Documentation

Now if we were working backward, we’d say to ourselves, “OK, to get an AVPlayer, we need to have a URL, so how do we do that?” In the documentation for init(url:), mousing over the URL reveals it to be a clickable hyperlink, so we could just follow that to get to its documentation. But let’s learn how to do a search, too. Click in the search bar at the top, and type URL. The results of the search will immediately appear in a sheet beneath the search bar, as shown in the screenshot.

There are a bunch of different kinds of hits. The URL structure we want is at the top of the figure, denoted by a “S” icon to indicate it’s a struct. There are other results, like classes that start with URL, and some guides on how to work with URLs in different APIs. If we clicked Show All Results, we would also see things like functions and methods that take URLs as their parameters. But let’s select that first result and go to the URL structure’s page. This documentation page is organized by topic, just like the last one, and under Initializers, we can find the one that takes a string.

So, by browsing, searching, and working backward, we can find the two classes we needed to create our streaming audio playground. We’ll have more to say about the language itself in the next few chapters, but whenever we need functionality that we believe the SDK provides, we now know we can just bring up the documentation viewer and look for it.