Headerdoc User Guide
Total Page:16
File Type:pdf, Size:1020Kb
HeaderDoc User Guide A User's Guide to Self-Documenting Code 2006-10-03 Helvetica is a registered trademark of Apple Computer, Inc. Heidelberger Druckmaschinen AG, © 1999, 2006 Apple Computer, Inc. available from Linotype Library GmbH. All rights reserved. Java and all Java-based trademarks are trademarks or registered trademarks of Sun No part of this publication may be Microsystems, Inc. in the U.S. and other reproduced, stored in a retrieval system, or countries. transmitted, in any form or by any means, mechanical, electronic, photocopying, Simultaneously published in the United recording, or otherwise, without prior States and Canada. written permission of Apple Computer, Inc., Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR with the following exceptions: Any person REPRESENTATION, EITHER EXPRESS OR is hereby authorized to store documentation IMPLIED, WITH RESPECT TO THIS on a single computer for personal use only DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A and to print copies of documentation for PARTICULAR PURPOSE. AS A RESULT, THIS personal use provided that the DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE documentation contains Apple’s copyright ENTIRE RISK AS TO ITS QUALITY AND notice. ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR The Apple logo is a trademark of Apple DIRECT, INDIRECT, SPECIAL, INCIDENTAL, Computer, Inc. OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR Use of the “keyboard” Apple logo INACCURACY IN THIS DOCUMENT, even if (Option-Shift-K) for commercial purposes advised of the possibility of such damages. without the prior written consent of Apple THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN may constitute trademark infringement and LIEU OF ALL OTHERS, ORAL OR WRITTEN, unfair competition in violation of federal EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any and state laws. modification, extension, or addition to this No licenses, express or implied, are granted warranty. with respect to any of the technology Some states do not allow the exclusion or limitation of implied warranties or liability for described in this document. Apple retains incidental or consequential damages, so the all intellectual property rights associated above limitation or exclusion may not apply to you. This warranty gives you specific legal with the technology described in this rights, and you may also have other rights which document. This document is intended to vary from state to state. assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, FireWire, Geneva, Mac, Mac OS, Macintosh, Sand, Velocity Engine, and Xcode are trademarks of Apple Computer, Inc., registered in the United States and other countries. Objective-C is a registered trademark of NeXT Software, Inc. CDB is a trademark of Third Eye Software, Inc. Contents Chapter 1 HeaderDoc Unfettered: API Documentation From Header Files 9 What is HeaderDoc? 9 How Do I Get It? 10 Organization of this Document 10 Chapter 2 HeaderDoc Tags 11 Introduction to HeaderDoc Comments and Tags 11 HMBalloonRect 13 Multiword Names 13 Automatic Tagging 14 Tags for Frameworks 14 Tags for All Headers 15 Tags Common to All API Types 20 Tags for All Languages 21 Availability Macro Tags 21 Constant Tags 21 #define Tags 22 Enum Tags 22 Function Tags 23 Function Group Tags 23 Struct and Union Tags 24 Typedef Tags 24 Variable tags 26 C Pseudoclass Tags 26 Class Tags 26 Interface Tags 27 Superclass Tags 27 Tags for C++ Headers 28 Conventions 28 Additional Tags for C++ Class Declarations 29 Tags for Objective-C Headers 32 Tags for Objective-C Headers 32 Chapter 3 Using HeaderDoc 35 Running headerDoc2HTML.pl 35 3 2006-10-03 | © 1999, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS HeaderDoc Command-line Switches 35 Running the Scripts Using MacPerl 36 Cocoa Front End 37 Using the C Preprocessor 37 Parsing Rules 37 Multiply-Defined Macros 38 Embedded HeaderDoc Comments in a Macro 38 Handling of #include 38 Other Issues 39 What if I Don’t Want to See the Macros in the Documentation? 39 Chapter 4 Using gatherHeaderDoc 41 Running gatherHeaderDoc.pl 41 Creating a TOC Template File 42 Using Multiple Landing Page Templates 44 Example gatherHeaderDoc Template 44 Chapter 5 Using the MPGL Suite 47 Man Page Generation Language (MPGL) Dialect 47 A Simple Function Example 49 A Simple Command Example 51 A Multi-Command Example 52 Chapter 6 Configuring HeaderDoc 55 Configuration File Example 57 Appendix A Symbol Markers for HTML-Based Documentation 59 The Marker String 59 Symbol Types for All Languages 60 Symbol Types for Languages With Classes 60 C++ (cpp) Symbol Types 61 Java (java) Symbol Types 61 Objective-C (occ) Method Name Format 61 C++/Java (cpp/java) Method Name Format 61 Appendix B HeaderDoc Class Hierarchy 63 Appendix C Troubleshooting 65 Common Error Messages 65 Unexpected Behavior 68 4 2006-10-03 | © 1999, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Other Issues 69 Chapter 7 HeaderDoc Release Notes 71 Languages Supported 71 Major Features 72 New Tags 73 Additional Notes 74 Document Revision History 75 5 2006-10-03 | © 1999, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS 6 2006-10-03 | © 1999, 2006 Apple Computer, Inc. All Rights Reserved. Tables and Listings Chapter 2 HeaderDoc Tags 11 Table 2-1 14 Table 2-2 15 Table 2-3 21 Table 2-4 21 Table 2-5 22 Table 2-6 22 Table 2-7 23 Table 2-8 23 Table 2-9 24 Table 2-10 24 Table 2-11 26 Table 2-12 26 Table 2-13 27 Table 2-14 27 Table 2-15 29 Table 2-16 30 Table 2-17 31 Table 2-18 33 Table 2-19 33 Listing 2-1 Example of multiword names using @discussion 13 Listing 2-2 Example of multiword names using multiple lines 13 Listing 2-3 Example of @header tag 20 Listing 2-4 Example of @availabilitymacro tag 21 Listing 2-5 Example of @const tag 21 Listing 2-6 Example of @defined tag 22 Listing 2-7 Example of @enum tag 22 Listing 2-8 Example of @function tag 23 Listing 2-9 Example of @functiongroup tag 23 Listing 2-10 Example of @struct tag 24 Listing 2-11 Typedef for a simple struct 25 Listing 2-12 Typedef for an enumeration 25 Listing 2-13 Typedef for a simple function pointer 25 Listing 2-14 Typedef for a struct containing function pointers 25 Listing 2-15 Example of @var tag 26 Listing 2-16 Example of @class tag 26 Listing 2-17 Example of @interface tag 27 7 2006-10-03 | © 1999, 2006 Apple Computer, Inc. All Rights Reserved. TABLES AND LISTINGS Listing 2-18 Example of @superclass tag 28 Listing 2-19 Example of documentation with @abstract and @discussion tags 29 Listing 2-20 Example of documentation as a single block of text 29 Listing 2-21 Example of @templatefield tag 31 Listing 2-22 Documentation tagged as abstract and discussion 33 Listing 2-23 Documentation included as single block of text 33 Listing 2-24 Example of @method tag 34 Chapter 5 Using the MPGL Suite 47 Table 5-1 MPGL block tags 48 Table 5-2 XHTML tags supported by MPGL 48 Table 5-3 Additional MPGL-specific inline tags 49 Listing 5-1 A simple MPGL example for a function 49 Listing 5-2 A simple MPGL example for a command 51 Listing 5-3 An MPGL example for multiple commands 52 Chapter 6 Configuring HeaderDoc 55 Listing 6-1 Sample HeaderDoc configuration file 57 Appendix A Symbol Markers for HTML-Based Documentation 59 Table A-1 HeaderDoc API reference language types 60 Table A-2 Symbol types for all languages 60 Chapter 7 HeaderDoc Release Notes 71 Table 7-1 HeaderDoc 8 Language Support 71 8 2006-10-03 | © 1999, 2006 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 HeaderDoc Unfettered: API Documentation From Header Files This document describes how to use the HeaderDoc tool. It also explains how to insert HeaderDoc comments into your headers and other files. This document corresponds with HeaderDoc 8.0. For information about previous versions, consult the documentation installed with your HeaderDoc distribution. What is HeaderDoc? HeaderDoc is a set of tools for embedding structured comments in source code and header files written in various languages and subsequently producing rich HTML and XML output from those comments. HeaderDoc comments are similar in appearance to JavaDoc comments in a Java source file, but traditional HeaderDoc comments provide a slightly more formal tag set to allow greater control over HeaderDoc behavior. HeaderDoc is primarily intended for use on Mac OS X, as part of the Mac OS X Developer Tools. However, in various versions, it has also been used successfully on other operating systems, including Linux, Solaris, and Mac OS 9. (Your mileage may vary.) In addition to traditional HeaderDoc markup, HeaderDoc 8 supports JavaDoc markup. HeaderDoc 8 also supports a number of languages: Bourne shell (and Korn and Bourne Again), C Headers, C source code, C shell, C++ headers, Java, JavaScript, Mach MIG definitions, Objective C/C++ headers, Pascal, Perl, and PHP. Most of these languages (besides C/C++/ObjC/Pascal) support documenting only functions or subroutines. Also included with the main script (headerDoc2HTML) is gatherHeaderDoc, a utility script that creates a master table of contents for all documentation generated by headerDoc2HTML.