Headerdoc Unfettered
Total Page:16
File Type:pdf, Size:1020Kb
HeaderDoc Unfettered May 27, 2004 CDB is a trademark of Third Eye Software, Apple Computer, Inc. Inc. © 1999, 2004 Apple Computer, Inc. Helvetica is a trademark of Heidelberger All rights reserved. Druckmaschinen AG, available from Linotype Library GmbH. No part of this publication may be reproduced, stored in a retrieval system, or Java and all Java-based trademarks are transmitted, in any form or by any means, trademarks or registered trademarks of Sun mechanical, electronic, photocopying, Microsystems, Inc. in the U.S. and other recording, or otherwise, without prior countries. written permission of Apple Computer, Inc., Simultaneously published in the United with the following exceptions: Any person States and Canada. is hereby authorized to store documentation Even though Apple has reviewed this manual, on a single computer for personal use only APPLE MAKES NO WARRANTY OR and to print copies of documentation for REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, personal use provided that the ITS QUALITY, ACCURACY, documentation contains Apple's copyright MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS notice. MANUAL IS SOLD ªAS IS,º AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE The Apple logo is a trademark of Apple RISK AS TO ITS QUALITY AND ACCURACY. Computer, Inc. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, Use of the ªkeyboardº Apple logo OR CONSEQUENTIAL DAMAGES (Option-Shift-K) for commercial purposes RESULTING FROM ANY DEFECT OR without the prior written consent of Apple INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages. may constitute trademark infringement and THE WARRANTY AND REMEDIES SET unfair competition in violation of federal FORTH ABOVE ARE EXCLUSIVE AND IN and state laws. LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, No licenses, express or implied, are granted or employee is authorized to make any modification, extension, or addition to this with respect to any of the technology warranty. described in this document. Apple retains Some states do not allow the exclusion or all intellectual property rights associated limitation of implied warranties or liability for with the technology described in this incidental or consequential damages, so the above limitation or exclusion may not apply to document. This document is intended to you. This warranty gives you specific legal assist application developers to develop rights, and you may also have other rights which applications only for Apple-labeled or vary from state to state. 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, Cocoa, FireWire, Geneva, Mac, Mac OS, Macintosh, and Sand are trademarks of Apple Computer, Inc., registered in the United States and other countries. Velocity Engine and Xcode are trademarks of Apple Computer, Inc. Objective-C is a trademark of NeXT Software, Inc. Contents Chapter 1 Introduction to HeaderDoc: API Documentation From Header Files 7 What is HeaderDoc? 7 Organization of this Document 7 Chapter 2 HeaderDoc Tags 9 Introduction to HeaderDoc Comments and Tags 9 HMBalloonRect 11 Multiword Names 11 Automatic Tagging 12 Tags for Frameworks 12 Tags for All Headers 13 Tags Common to All API Types 17 Tags for All Languages 17 Availability Macro Tags 17 Constant Tags 18 #define Tags 18 Enum Tags 19 Function Tags 19 Function Group Tags 20 Struct and Union Tags 21 Typedef Tags 21 Variable tags 23 C Pseudoclass Tags 23 Class Tags 23 Interface Tags 24 Superclass Tags 24 Tags for C++ Headers 25 Conventions 26 Additional Tags for C++ Class Declarations 26 Tags for Objective-C Headers 29 Tags for Objective-C Headers 29 Chapter 3 Using HeaderDoc 33 Running headerDoc2HTML.pl 33 HeaderDoc Command-line Switches 33 3 May 27, 2004 | © 1999, 2004 Apple Computer, Inc. All Rights Reserved. CONTENTS Running the Scripts Using MacPerl 34 Cocoa Front End 35 Chapter 4 Using gatherHeaderDoc 37 Running gatherHeaderDoc.pl 37 Creating a TOC Template File 38 Using Multiple Landing Page Templates 40 Example gatherHeaderDoc Template 41 Chapter 5 Using the MPGL Suite 43 Man Page Generation Language (MPGL) Dialect 43 A Simple Function Example 45 A Simple Command Example 47 A Multi-Command Example 49 Chapter 6 Configuring HeaderDoc 51 Configuration File Example 53 Appendix A Symbol Markers for HTML-Based Documentation 55 The Marker String 55 Symbol Types for All Languages 56 Symbol Types for Languages With Classes 57 C++ (cpp) Symbol Types 57 Java (java) Symbol Types 57 Objective-C (occ) Method Name Format 57 C++/Java (cpp/java) Method Name Format 58 Appendix B HeaderDoc Class Hierarchy 59 Chapter 7 HeaderDoc Release Notes 61 Languages Supported 61 Major Features 62 New Tags 63 Additional Notes 64 4 May 27, 2004 | © 1999, 2004 Apple Computer, Inc. All Rights Reserved. Tables and Listings Chapter 2 HeaderDoc Tags 9 Listing 2-1 Example of multiword names using @discussion 11 Listing 2-2 Example of multiword names using multiple lines 12 Listing 2-3 Example of @header tag 16 Listing 2-4 Example of @availabilitymacro tag 17 Listing 2-5 Example of @const tag 18 Listing 2-6 Example of @defined tag 18 Listing 2-7 Example of @enum tag 19 Listing 2-8 Example of @function tag 20 Listing 2-9 Example of @functiongroup tag 20 Listing 2-10 Example of @struct tag 21 Listing 2-11 Typedef for a simple struct 21 Listing 2-12 Typedef for an enumeration 22 Listing 2-13 Typedef for a simple function pointer 22 Listing 2-14 Typedef for a struct containing function pointers 22 Listing 2-15 Example of @var tag 23 Listing 2-16 Example of @class tag 23 Listing 2-17 Example of @interface tag 24 Listing 2-18 Example of @superclass tag 25 Listing 2-19 Example of documentation with @abstract and @discussion tags 26 Listing 2-20 Example of documentation as a single block of text 27 Listing 2-21 Example of @templatefield tag 28 Listing 2-22 Documentation tagged as abstract and discussion 30 Listing 2-23 Documentation included as single block of text 30 Listing 2-24 Example of @method tag 31 Chapter 5 Using the MPGL Suite 43 Listing 5-1 A simple MPGL example for a function 46 Listing 5-2 A simple MPGL example for a command 47 Listing 5-3 An MPGL example for multiple commands 49 Table 5-1 MPGL block tags 44 Table 5-2 XHTML tags supported by MPGL 45 Table 5-3 Additional MPGL-specific inline tags 45 5 May 27, 2004 | © 1999, 2004 Apple Computer, Inc. All Rights Reserved. TABLES AND LISTINGS Chapter 6 Configuring HeaderDoc 51 Listing 6-1 Sample HeaderDoc configuration file 53 Appendix A Symbol Markers for HTML-Based Documentation 55 Table A-1 HeaderDoc API reference language types 56 Table A-2 Symbol types for all languages 56 Chapter 7 HeaderDoc Release Notes 61 Table 7-1 HeaderDoc 8 Language Support 62 6 May 27, 2004 | © 1999, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Introduction to HeaderDoc: 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. 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. 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. Information on running gatherHeaderDoc is provided in ªUsing gatherHeaderDocº (page 37). Both scripts are typically installed in /usr/bin, as headerdoc2html and gatherheaderdoc. Finally, HeaderDoc comes with a series of tools for man page generation, xml2man and hdxml2manxml. The first tool , xml2man, converts an mdoc-like XML dialect into mdoc-style man pages. The second tool, hdxml2manxml, converts HeaderDoc XML (generated with the -X flag) into a series of .mxml files suitable for use with xml2man. Organization of this Document This document is divided into several chapters describing various aspects of the tool suite.. ■ ªHeaderDoc Tagsº (page 9) explains how to add HeaderDoc markup to header (and source code) files. What is HeaderDoc? 7 May 27, 2004 | © 1999, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Introduction to HeaderDoc: API Documentation From Header Files ■ ªUsing HeaderDocº (page 33) explains the syntax for the HeaderDoc command-line tool itself. ■ ªUsing gatherHeaderDocº (page 37) explains how to use gatherHeaderDoc to produce landing pages and cross-linked trees of related documentation. ■ ªUsing the MPGL Suiteº (page 43) exmplains how to use the Manual Page Generation Language (MPGL) tool suite. ■ ªConfiguring HeaderDocº (page 51) explains the HeaderDoc configuration file. ■ ªSymbol Markers for HTML-Based Documentationº (page 55) describes the symbol markers used by HeaderDoc and various other utilities to provide linking functionality. ■ ªHeaderDoc Class Hierarchyº (page 59) describes the class hierarchy of the HeaderDoc tool itself.