Meet DocC documentation in Xcode

Hi, I'm Victoria. I'm an engineer on the Documentation Tools team here at Apple, and together with my colleague Ethan, we're going to give you an introduction to the new documentation features in Xcode 13. There are new ways to read and write documentation that both fit right into your workflow and unlock new possibilities for your development. Xcode 13 has new features to build, write, and browse documentation for Swift frameworks and packages. This unlocks a powerful mode of documentation-driven development where you can read all about your Swift dependencies while you write your code. This documentation lives right alongside the platform libraries in the Developer Documentation window right in Xcode. In this session, we'll give an overview of the documentation features in Xcode 13, walk you through building documentation for the Swift frameworks and packages you're writing and using, show you how you can use Xcode 13 to write great documentation, and finish up by showing off the ways you can share documentation with Xcode 13. Let's get started with why I'm personally excited about the new documentation features. I'm sure we've all been there. There's some new framework or package that we want to use, but when it comes time to integrate it into our code, we need to figure out what all comes in it. This is where Xcode 13 steps in. Now Xcode comes with a compiler for your documentation as well as your code, and you can build and view documentation for Swift frameworks and packages all inside Xcode. We call it DocC, and we've integrated it all throughout Xcode to enhance the way you read and write documentation. Now, DocC is more than just a documentation compiler run after the fact. It's a fully integrated documentation environment that complements Xcode, offering a rich, live environment with your docs appearing in Quick Help, rich code completion to allow you to tie your docs together into a cohesive whole, full documentation available in the integrated Developer Documentation window, and an easy option to share pre-built documentation to view in Xcode and on the web, just to name a few. Stay tuned for our other DocC sessions at WWDC 2021, which will go over all these in detail and much more. DocC empowers you to write excellent reference documentation, leveraging the power of Xcode and Swift to give users a bird's-eye view of the public APIs in your framework or package, complete with the ability to describe how APIs work together, not just in isolation. DocC enables you to write much more than great reference documentation, though. There are two additional ways to write documentation with DocC that we're excited to show off this year. Articles allow you to walk users through the big picture behind your framework, giving you an opportunity to tie individual items in your framework together with a cohesive story. And tutorials are a powerful step-by-step walk-through of writing a project that uses your framework. They allow you to go much deeper than reference documentation or articles by giving your users a guided introduction to your framework from the ground up.

All of these authoring experiences leverage and extend the power and simplicity of Markdown to make authoring your documentation as fluid as writing your code. If you want to know more about assembling a documentation catalog with articles and tutorials outside your source code, check out these sessions at WWDC this year.

And finally, we're releasing DocC as Open Source later this year, alongside a web app that allows you to host your built documentation archives on the web so you can take advantage of these new documentation workflows even outside of Xcode. Now that you have a taste of the new documentation features in Xcode 13, let's dive in and talk about building your documentation with DocC in Xcode. Let's take a quick peek under the hood first to see how it works. To build your documentation, Xcode builds your framework or package and asks the compiler to save information about its public APIs alongside your compiled artifacts. That public API information is then handed to DocC, which then combines it with your documentation catalog containing articles and tutorials written outside your source code to create the final archive containing the compiled documentation. To learn more about documentation catalogs and organizing your docs, check out the “Elevate your DocC Documentation in Xcode” session. And thanks to DocC's integration with Xcode's build system, this process repeats for every Swift framework and package that your target depends on. This way, you have all your relevant documentation all in one place. But what does this mean for your day-to-day documentation needs? There are three ways to build documentation for Swift frameworks and packages in Xcode 13.

To build documentation on demand, there's a new Build Documentation menu item to compile and load up your docs. And if you're working on a Swift framework and always want to preview your documentation as you go, there's also a new build setting to build docs every time you compile. And for your command-line and CI needs, xcodebuild has a new command to build documentation too. This runs the same build as selecting Build Documentation in Xcode but using xcodebuild on the command line. My colleague David has much more information about automating documentation workflows in the “Host and Automate your DocC Documentation” session. Let's see this in action. My teammates have been working on this package called SlothCreator, which is all about cataloging and customizing cute little sloths. I want to try it out, so let's see how that looks in Xcode 13. I've set up this app I've called Slothy so I can use SlothCreator to customize my sloths and preview them as I go. I've set up SlothCreator as a dependency of my app already, but I want to see more about what APIs it offers, so let's open up the Product menu...

And select Build Documentation to take a look.

And just like that, the Developer Documentation window opens, and over in the Navigator, I can expand my Slothy project and the SlothCreator package I'm working with to see an overview in the Navigator. I'll load the SlothCreator overview in the main view, and if I scroll down, there's a list of types and protocols available.

Here I can see this type called Habitat. Let's click on it to load its page.

There's some good information here, but I wonder if anything else has mentioned it. Let's select the Search field up top and look for "habitat".

It looks like a few different things mention this. Let's click on this sleep method to bring up its documentation page.

This page is specific to the sleep method, but I'm curious what type this is part of. Up in the jump bar at the top of the window, I can see this is part of the Sloth type.

If I click this Sloth, a pull-down menu appears, and if I click it again, I can open that type's documentation page. Now I'm getting a picture of how all these APIs fit together. So now we've had a chance to walk through the documentation of SlothCreator. Let's rewind and take a look to see how it got to that point. My colleague Ethan will start off by showing some of the new features in Xcode 13 to write great documentation. Take it away. Thank you, Victoria. Now that we've gone over Xcode 13's great support for building and browsing documentation, I'd like to show you a few tricks to write even better documentation with DocC.

DocC is designed around the benefits of in-source documentation. You write your documentation right alongside your code, making it convenient and easy to integrate with your existing development workflow.

To add documentation to a declaration, you just write a special kind of comment directly above it. This makes it easy to keep your documentation in sync with any code changes you might make in the future. And, of course, it will fit right in with your existing text-based tooling, like Git diffs.

You're likely already annotating your source code with comments to provide extra context to future maintainers of your codebase. In Swift and many other languages, you write a comment by starting your line with two forward slashes.

By writing these comments, you've gone a long way in helping future maintainers to understand and be productive within your codebase. But what if you want to help today's adopters of your framework? This is what documentation comments are for.

By writing a comment that begins with three forward slashes, you're telling the Swift documentation compiler to associate the comment with the declaration immediately below it. The comment will be included in the symbol's compiled documentation page and accessible to anyone who imports your framework. And if you prefer to use block-style comments, you can create a documentation comment in that style by just including an extra asterisk in the opening delimiter. Let's see how this all works in practice. As Victoria mentioned, over the last few months, we've been working on the SlothCreator framework. SlothCreator is a Swift package that provides functionality for cataloging and customizing cute sloths. As a developer of SlothCreator, I want to be sure that there's an easy way for any adopters of the framework to get started, so I've been working on adding documentation comments to the parts of the codebase I worked on. In particular, I want to be sure that every public API in SlothCreator is well documented, because it's these API that are accessible to anyone importing my framework. For the same reason, DocC only generates documentation pages for the public and open symbols in your framework. There's just a couple of symbols in SlothCreator that still need documenting. Let's start with this Food struct. I'll begin by adding three forward slashes above the type's declaration to create a documentation comment. And then I'll write that this is "Food that a sloth can consume." The first line of my documentation comment will turn into the symbol's summary, but I'd like to add some extra information with a discussion section. I'll add one now by adding a line break after my summary and then adding some additional detail about the kinds of foods sloths love. And because DocC has full support for Markdown, I can add a code example using Markdown's fenced code block syntax.

Great. I think this adds some really helpful additional context around the Food struct. Let's see how my documentation is looking now by rebuilding documentation. I can do that by moving my mouse up to the Product menu and then selecting Build Documentation.

Xcode will now rebuild SlothCreator's documentation alongside the framework itself. And because I used the Build Documentation button for this build, when it's complete, the documentation viewer will open with my updated documentation. But I'm actually interested in going straight to the page for the Food struct to review the comment we just added. Fortunately, Xcode has a feature called Quick Help that will let me do just that. Quick Help offers a short summarized version of a symbol's documentation right in the source editor.

I can try it out now by holding down the Option key and then clicking on Food's declaration. But an adopter of SlothCreator could open the same view by option-clicking on any reference to the Food struct in their code. So the comment we wrote is right here in the Summary and Discussion sections. But if I'm looking for more than the summarized view, new in Xcode 13 is the Open in Developer Documentation link.

If I move my mouse to the bottom right-hand corner of the Quick Help view and click on Open in Developer Documentation, the documentation window will launch right to that symbol's page. Awesome. There's one other symbol that's still missing documentation in SlothCreator. I'll open the Sloth file by moving my mouse over to Xcode's Navigator and clicking on the Sloth item. And if I scroll down, I'm noticing that the Eat method still needs a documentation comment. So let's take a quick look at the best way of documenting methods.

We start the same way, by adding a triple-slash comment above the method's declaration and adding text that will make up its documentation summary. But we should also document specifically what we're expecting to be passed as a parameter.

We do this via a Parameters section. You add a Parameters section to your documentation by writing a Markdown list item starting with the word Parameter followed by the name of your method's parameter, a colon, and then its documentation. You can add a Returns section in a very similar way, this time by writing a Returns delimiter followed by a colon and a description of what your method returns. But what if your method has multiple parameters? In this case, the best thing to do is to go from a singular Parameter delimiter to a plural Parameters one. This works much the same as the others except your parameter names are written as children of the parent Parameters delimiter. So now that we've gone over the basics, let's document the sloth Eat method. Now, I could begin the same way we did when documenting the Food struct by manually writing a documentation comment beginning with three forward slashes. But since I'm documenting a more complicated symbol, I'm going to take advantage of Xcode's great Add Documentation feature which will insert a template best-suited for documenting the current declaration.

I can do this by holding down the Command key and then clicking on the method's declaration to open the Action menu. Next, I can click on Add Documentation in the Action menu and, just like that, I have a great template to get started documenting my method.

I'll begin by filling out the method's summary, and then I'll describe the food and quantity parameters as well as what this method returns. And then I'll finish off the documentation by adding a Discussion section along with a code example.

Just like last time, I can rebuild documentation by moving my mouse to the Product menu and selecting the Build Documentation item.

And once again, Xcode is building my documentation alongside the framework itself. This time, I'll navigate to the Sloth struct via the window's Navigator, where I'll find Sloth in the Sloths topic group. If I scroll down on the Sloth page, I'll find my method in the Instance Methods section...

Along with my updated documentation. I'm already really happy with it. The inputs and outputs of the method are really well defined, and there's a helpful code example here as well. I think this is nearly ready to go, but we're still missing something here. If I'm just reading this page of documentation, I don't have a great context of the other relevant symbols I should be considering here. And as a maintainer of SlothCreator, I'd really like to call out some other symbols that my reader should consider learning about next. Well, new to Xcode 13 is the ability to link to symbols in your documentation. This is a really great way to connect different parts of your framework and guide your reader to relevant pieces of information. You write these links via a new double backtick syntax. Let's look at an example.

Here's the method we previously documented, sleep. But it doesn't exist in a vacuum. There's actually another property in the Sloth struct.

There's a value representing the current energy level of the sloth, and I think it's important here for my reader to understand that one of the side effects of calling sleep is a change to the sloth's energy level.

So I'll add to my methods Discussion section here with a reference to the energyLevel property.

Before Xcode 13, the natural way to do this would be to just write the property's name in a monospace code font by surrounding it in backticks. But now I can transform to double backtick syntax and create a link. Now, linking to energyLevel was pretty simple because that property is a sibling of the method I'm documenting, and just like when referencing a local variable in Swift, I don't need to further qualify my link with the parent type. I can just write the name of the property, energyLevel.

But if I want to reference a child of a different type, I need to be a little more specific. So here I write Habitat/comfortLevel to link to a child of the Habitat struct. Great. Let's see how this works in practice by adding some links to the documentation for the eat method. I'll begin here by writing that "When they eat food, a sloth's..." and now I'm going to write a symbol link to the energyLevel property. So I'll type two backticks, and then I'll begin writing energyLevel. Xcode's code completion will help me out to make sure I'm getting the correct link. I'll go ahead and select that item.

And so I'll say that the energy level "increases by the food's"-- and now I'm going to reference a child of the Food struct. I'll begin with two backticks again. And then I'll write Food, a forward slash, and then energy.

I've now created two symbol links which I think are going to really help my reader understand the context around this method better. And these links are even accessible in Quick Help. So I'll hold down the Option key and click on my method's declaration to open the Quick Help popover. Here's the Discussion section we added and, of course, in the discussion, our two links. And if I click on one, I'm brought straight to the referenced symbol's page in the documentation window. Now that I've written a good documentation comment for every public API in SlothCreator, I'm really excited to share it with my colleagues and maybe even make it available on the web. I can do this via the documentation archive that Xcode outputs as part of every documentation build. Contained in the documentation archive is a single-page web app that you can use to share your documentation on the web. My colleague David will be going in depth on just how to do that in his “Host and automate your DocC documentation” session. I highly recommend you check that one out.

But Xcode also supports exporting and importing your documentation directly from the documentation window. Let's take a look at that now. I'll export SlothCreator from the documentation window by first moving my mouse over to the window's Navigator. When I hover over the SlothCreator framework item, a contextual menu icon will appear. I'll click on it, and now I have the option to Export.

I'll just save it to my desktop. Great. Now I'm ready to send it off to my colleagues, and if they just double-click on the archive, it will open in Xcode's documentation window. But since I already know about SlothCreator, I'd like to open up a different documentation archive. I've recently been discussing with the team that it would be great to add a command line interface to SlothCreator, and one of my colleagues mentioned that ArgumentParser is a great open source framework that could help. They sent me the latest documentation archive for ArgumentParser, so let's open it up now. I can just double-click on the documentation archive and, just like that, get started learning right away. Documentation is key to developing a successful and long-lasting framework. We think that you'll find writing documentation directly in source is really convenient and powerful. And new in Xcode 13 with DocC integration, all your hard work writing great documentation is going to pay off in new and powerful ways.

We have several other sessions at WWDC that really help you take your documentation to the next level. “Elevate your DocC documentation in Xcode” picks up where this session leaves off, showing you how to better organize your documentation by adding a documentation catalog. “Host and automate your DocC documentation,” which I mentioned earlier, explains how to integrate documentation builds into your existing continuous integration setup as well as how to host your documentation online.

Finally, if you have a more complicated part of your framework that could benefit from step-by-step instruction, I recommend you check out “Build interactive tutorials in DocC” which will show you how to do just that.

Thank you for watching. [percussive music]