If it has finished, try restarting Xcode, just to make sure. Troubleshooting: If your popover didn’t contain your comment, you may not have waited long enough for the project to build. You should see a popover with your comment. When it finishes, hold the option key, and click on the car variable name. * The ViewController class' car (nonatomic) Car *car Just above the declaration for the car property, add a comment block so that it looks like this: You’ll see two properties that are lacking some documentation. Let’s start by documenting a few properties.īack in Xcode, in the DocumentationExamples project, open ViewController.h. (You can also use the equivalent is by no means all of the tags, and you can find all of the available tags in the HeaderDoc User Guide.įor the sake of this tutorial, all comments will be placed in the header files, just to keep the implementation files clean. A description of what a method or function returns.The name and description of a parameter to a method, callback or function.It’s not required to actually write this keyword out but it is good to use for clarity’s sake. Equivalent to Similar to and but it allows multiple lines.Quickly describes the data type, method, etc.Let’s take a look at some helpful Second-Level tags: In this tutorial, you’ll focus mostly on Second-Level tags. HeaderDoc is pretty good at adding Top-Level tags automatically via the context, so they are generally optional. Second-Level Tags: These tags help to give more detail about the specific thing you are commenting.Īn example of a top-level tag is which you use to indicate typedefs for things like enums, structs and function pointers.Top-Level Tags: These are tags that declare the type of thing you are commenting (Headers, classes, methods, etc.).You will use tags to mark-up your code.Ī tag starts with the symbol and a keyword, followed by a space, and a string that contains a description relative to that keyword (such as foo). Once HeaderDoc finds a comment in one of the above styles, it will search that comment for tags for more information. For single line comments, use the triple forward slash syntax ( ///) comment to save room.For large comment blocks, use the style used in Apple’s documentation ( /*!).Since we could start a small war over which way is the “best” way to document your code, we’ll stick with the following rules for the purposes of this tutorial: This is purely aesthetic, and is not required.Īll three syntaxes will produce the same result, if done in Xcode. Note: In options two and three, there is an additional asterisk on each line in-between the required opening and closing lines. Note that these are similar to “normal” comments, except that there’s an extra / in option 1, and an extra character in the first line of options 2 and 3 ( * and !, respectively). * Your documentation comment will go here / Your documentation comment will go here There are three styles of comments that HeaderDoc scans for: Basically it scans your files for comments made in a particular style. HeaderDoc is a tool that you can either run from the command-line, or is automatically run by Xcode. Let’s see how you can use HeaderDoc to make creating documentation for these classes super easy. Right now, these files are barely documented. MathAPI: Contains a helper method to add two numbers.Car: Contains a few properties, and a method to “drive” a car and run a block upon completion.This is a simple little test project that includes two main helper classes: Learn about a third-party tool to make documentation even easier ( VVDocumenter-Xcode)ĭownload the starter project for this tutorial, and build and run.Generate HTML documentation from your comments.In this HeaderDoc tutorial, you will learn how to: In addition, Xcode parses HeaderDoc-style comments behind the scenes to automatically present your documentation in quick look panels. HeaderDoc is a command line tool that you can use to automatically generate nice HTML documentation for your code – as long as you structure your comments in a particular way. When Xcode 5 and iOS 7 were announced, a small addition was mentioned that most people might have missed: HeaderDoc.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |