Lines Matching refs:to
15 This article explains how to document the API. Its intended audience are the
16 Haiku developers who want to document their own classes, and also the
17 members of the API Documentation team who want to brush up the
20 applicable. If you find an inconsistency, it's usually a good idea to
28 you are a developer and you want to prepare the first version of the
29 documentation for the API documentation team to go over, have a good look at
31 glance at how to write member and class documentation, since you'll need to
34 carefully, and should also check out some of the finished documentation to
41 like and how to put delimiters to separate different 'blocks' in your source
46 Doxygen, the tool that we use to generate the marked up documentation, has
47 an ingenious parser that is able to scan through both header and source
48 files making it possible to document the API directly in the headers or the
49 source. However, the Haiku project have decided not to put the documentation
50 in either location, and opt for the third option Doxygen provides: to put
53 \note The reasons to not put the documentation in the header files are
54 twofold. First of all, it would add unnecessary cruft to the headers
55 that the compiler will needlessly have to parse. File access and speed
58 electricity to have everybody recompile the entire tree if someone fixes
59 a typo in the documentation. Likewise, the reason to not put the
62 like the fact that developers might be inclined to update the
64 have some methods in place to prevent that to a certain extent.
65 There are a few aspects to the naming and locations of files:
68 of the methods, variables, functions, etc. will have to be the same.
80 copyright block, with a reference to the author(s) and against which
92 * Corresponds to:
104 -# The first line is empty, then we get to the copyright notice. You may
105 either retain the copyright yourself, or you can attribute to to Haiku
113 -# The final part is underneath the label <tt>Corresponds to:</tt>.
115 current documentation is known to correspond with.
122 feel like overkill to use blocks, but realize that Doxygen was initially
123 designed to operate on header and source files, and then the blocks of
125 functions, etcetera. Doxygen is used to operating on blocks, and that's why
126 we need to reproduce them in our \c dox files.
128 Blocks should adhere to the following standards:
135 not to cross this limit</em>, because it will severely limit
142 \brief Append an item to the list.
144 \param item The item to add.
159 complex header and for the sake of clarity in your \c dox file you want to
189 will have to indent subsequent lines that belong to the paragraph with
190 two more spaces, making the total of four. This is to visually
196 Doxygen needs to be helped with figuring out what the documentation in the
201 Tells Doxygen that the following section is going to be on the class as
204 This block is going to be about the function that corresponds to the
207 scope operator, \c ::, are to be added as well. Modifiers such as \c
210 This block is going to be about the variable indicated by the
214 This block is going to be about the typedef indicated by the
218 Tells Doxygen the section is going to be on the \c struct indicated by
221 This block is going to be about the \c \#define with the identifier \a
231 belongs to a certain section should be placed after a command that marks the
251 This section contains references to other parts of the documentation.
254 documentation. See the style section to find out the appropriate situations
255 in which to use them.
264 Sometimes you might require certain text to have a special markup, to make
265 words stand out, but also if you want to have example code within the
269 letter commands are commands that work on a the next word. If you need to
271 blocks of code or blocks of text that need to be in "typewriter" font, use
275 Use to refer to parameters or arguments in a running text, for example
276 when referring to parameters in method descriptions.
281 This can be used to refer to constants, or anything that needs to be in
289 parse the contents and try to mark up the code to make it look a
300 Important to know is that a page is the complete length of the block, so
302 Doxygen provides some commands to structure text on a page.
308 to be a page, you can start writing the contents.
310 For more complicated pages, you might want to divide the page up in
311 sections. Use the \c \\section command to define a new section. It takes the
314 and \c \\subsubsection, again, both with the same syntax. If you need to
315 distinguish between sections in subsubsections, you are able to use
318 \note Before and after each of the commands above, you need to have an empty
319 line so as to provide readability. It is not necessary to indent
324 think about the nature of your page. Either it needs to be split up into
328 If you are creating multiple pages that are related, you will be able to
336 Doxygen makes it possible to group certain members together. It is used
343 \note If you are looking on how to add classes to kits, see
347 about. You are required to give each group of members at least a name. Have
354 These methods append things to the object.
368 long. See the \ref style section on how to effectively write group headers.
369 The members that you want to belong to the group are between the group
380 The first one is \c \\n. This commands sort of belongs to the category of
382 paragraphs as a single contiguous entity, it's not possible to mark up the
386 Sometimes there are some parts of the API that you don't want to be visible.
388 and virtually every member from a file, you might want to force it to hide
394 Images can be a valuable addition to documentation. To include ones you
397 \c html. The file refers to the filename relative to the location of the
398 documentation file. Any images you want to add should be in the same
401 Modules are defined in the main book, and you can add classes to them by
402 using the \c \\ingroup command. This commands adds the class to the module
404 to be finalised. For now, add the classes to the kit they belong in. In the
407 Finally, it is a good idea to link between parts of the documentation. There
408 are two commands for that. The first one is \c \\ref, which enable you to
409 refer to pages, sections, etc. that you created yourself. The second one is
410 \c \\link which refers to members. The first one is takes one word as an
414 referred to, and the rest is the link text.
419 documentation. Both the structure of the documentation, which sections to
422 and pages, there are some general remarks that apply to all types of
426 sentences</em>. Spelling, grammar, punctuation, make sure you adhere to the
434 - Avoid informalism. Avoid constructs like 'if you want to
435 disconnect the object', but rather use 'to disconnect the object'. Avoid
438 \remarks It isn't the goal to create dry, legal-style documentation. Just
439 try to find a balance. Read through documentation that's already been
440 approved to get a hint of what you should be aiming for.
442 down in such a way that it says everything it needs to. A proofreader
443 might then be able to rephrase it to a better style.
445 Throughout the documentation you might want to provide hints, warnings or
446 remarks that might interrupt the flow of the text, or that need to visually
451 Notes on what to read first, or mistakes that may be made by beginners
454 - The point needs to visually stand out. This is especially the case with
456 - The point is not completely relevant to the text and therefore should be
459 This listing shows which one to use for which situation:
461 - Used when the developer is bound to make a mistake, when the API is
466 - Used to warn for abuse of the API that might be caused by the way the
469 - Used to warn developers about using the API in a certain way. Warnings
470 apply especially to new developers that aren't completely familiar
471 with the API and that might want to abuse it. For example, the
474 - Used to place references to other documentation that might not be
475 directly related to the text. For example, BLooper will have a
476 direct reference to BHandler in the class description, but
479 - Can also be used for useful hints or notes that somehow need to stand
485 text to tell that you have been lying.
487 to it.
492 as inconvenient. At the moment, how to actually group the documentation is
494 needs to be documented before the members of that header can be documented.
516 rather a range of different functions and defines, so the text refers to
529 to include every item, it merely serves as a guiding principle that helps
534 provide read and write access to data." Note that this description is
537 do. Describe things like what it works on, when you want to use it, what
539 describe if a class is made to be derived from, and if so, how. Make
541 wants to do can be done with this class.
547 examples adhere to Haiku's coding guidelines. Remember, an example can
549 -# End with a list of references to other classes, functions, pages, etc.
550 that might be of interest to the reader.
552 When documenting classes, don't be to exhaustive. Avoid becoming a tutorial
554 to enlighten the reader on bigger subjects, consider writing a separate
555 documentation page that connects the different points you want to make.
557 Also, you don't have to put in any groupings of members in class
558 descriptions. If you want to do that, physically divide the members up in
567 writing the actual documentation. There are some guidelines as to how, but
572 line needs to match the declaration, which is in the source file. This
574 should be present. Also note that this line doesn't have to adhere to
582 more depth. Don't be too verbose, and use an example to illustrate
584 developers to have, but don't repeat the class documentation too much.
585 -# You are obliged to then document all the parameters. Use the \c \\param
587 offset (zero based) where to begin the move." Note the capital and the
589 -# If the function is non-void, then you'll have to specify what it will
595 -# Use \c \\see if you have any references to other methods, classes or
600 In case of overloaded members, you'll need to make a decision. If you need
601 to copy too much information, you might resort to putting it in one
604 copying down and will point developers right to the place where they can get
607 Again, like class descriptions, you'll have to find a good middle-ground
609 audience possible, and resort to notes and warnings for specialised
615 constants, as well as enumerations and their values. If you need to document
629 If you are planning to derive from this object and you want to manipulate
634 The variables you are going to encounter are either \c public or
636 significance. In the case of member variables, you'll need to document what
638 that is meant to be derived from, make sure that in the description of the
645 depend on that constant. If the variable is meant to be changed by the
662 indicator. Give a short description of the value, which methods react to
663 it, where it might be used, etcetera. Don't go as far as to copy information
666 enumeration documentation: rather just refer to it. That sort of
667 documentation belongs to the class description, not to the enumeration.
671 If you subdivide members of classes into groups, you have the ability to
673 members in that group. See the section \ref commands_grouping on how to
674 define groups. This section is on what to put in the header block.
676 First of all, it's probably a good idea to give your group a name. This name
682 It's possible to add one or two paragraphs of information. These paragraphs
683 should contain some quick notes on which of the members in that group to use
685 as a guide to see which method he actually wants to use. Don't go on
700 See the String.h documentation file to see the specifics, as they are
705 Straight, to the point, gives no more information than necessary. Divides
706 the members up into two groups and refers to other functions the developer