![]() As it’s evolving, the project is starting to add in the capability for documenting apps as well. This is the text beneath the overview that starts with # Topics, followed by one or more 3rd level headers ( #) with various grouping names.ĭocC started with collating only public types, methods, protocols, and so on for libraries and frameworks. When I suggest adding top-level curation, I’m referring to adding organization to that top-page in your library, that includes the overview. In the world of DocC, curation is a term that means to create organization for a set of symbols. 4 – Add the top-level curation for your library. The bottom section of the template (this text that starts with # Topics and has a placeholder 3rd level heading with a generic symbol underneath) is the placeholder for you to organize the symbols of your project – the next tip. I recommend writing the content under the Overview heading first, and then going back and writing the summary later. It is intentionally, and specifically, structured for DocC. When you create a documentation catalog using Xcode, its template includes a markdown file with a loose structure for what to add. I created an earlier post ( Hosting Your Swift Library Docs on Github Pages) that goes into detail on the steps of doing just that. There is also terminal commands to generate documentation that’s suitable for static hosting. You can export an archive for others to use from that window. When you add a catalog and then use Product > Build Documentation within Xcode, those docs appear in the Xcode documentation window. It houses the top-level overview of your library, and any assets (images, articles, and more - should you go that far). The documentation catalog is a directory with a collection of goodies. It provides an introduction and framing to your library, and is the heart of where to learn more. I think of the Documentation Catalog as being akin to the idea that you should include a README file with a project. Everything above provides immediate benefit while you (and any collaborators) work on, or with, the source code. ![]() 3 – Add a documentation catalog and a library overview.Īdding a documentation catalog is the 3rd thing on this list – that’s not a mistake. But there is still a lot you can do to make it easier to use your library. If you stop right after doing this, you have the basic, effective documentation that is available to anyone loading your framework or package. If you do this for a function or method, it includes the parameters formatted correctly for DocC and placeholders for you to fill in. If you’re writing the doc comments using Xcode, it provides a handy “generate a doc comment” command ( command-option-/ being the default key mapping to that Xcode gem) that creates a stub. If it’s more complex, add that after a break (a line with /// and nothing else as a doc comment), then talk to the details on how to use it, or what to expect. For those times, a single line summary (the first line with ///) does wonders. Sometimes its simple – and a single line abstract describing what it represents is more than sufficient. Aim to get to the core of what the symbol does – and most importantly, why you’d use it and what you need to use it. This is about the the elements on your type (struct, class, enum, or whatever) that make it unique and special. The important bit here isn’t a default initializers or functions that enable conformance to common standard library protocols. 2 – Add doc comments to your public methods and properties. And that is where the much-commented-on No Overview Available comes from. When a symbol (whether it’s a class, struct, protocol, property, or method) doesn’t have an abstract, DocC generates one for you. The initial single line doc comment is referred to as the abstract. You get maximum immediate benefit, as it provides content to the panel that opens when you option-click on a type. The reason I picked this as the starting point is that everything you add immediately becomes available through Xcode’s quick-help. This is a great place to drop in a code snippet showing how to use that type alongside the discussion of what it is and how to use it. Feel free to add more: if you add a “blank line” (meaning include another line with /// but nothing else in it) followed by additional content, that content appears as the “Discussion” or “Overview” for the type. The starting point is adding a single short summary sentence as comment (using the ///) for each public type in your library or app. 1 – Start by adding doc comments to your types.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |