Lines Matching refs:that
22 Guidelines, which means that the formal requirements are the same where
27 describes the demands that are made from the markup and spacing of the
49 Doxygen, the tool that we use to generate the marked up documentation, has
50 an ingenious parser that is able to scan through both header and source
57 First of all, it would add unnecessary cruft to the headers that the
59 time to find the info they are looking for. The second reason is that
63 documentation in the source code is that it unnecessarily clutters up
64 that file. By not using direct documentation we lose some advantages,
65 like the fact that developers might be inclined to update the
67 have some methods in place to prevent that to a certain extent.
70 not only means that they get the same name, but also that the order
103 The example above has a few elements that you should take note of:
125 Underneath there is a list of files and their svn revisions that the
136 feel like overkill to use blocks, but realize that Doxygen was initially
139 functions, etcetera. Doxygen is used to operating on blocks, and that's why
190 It is possible that there is documentation for parts of the API that are
191 not (yet) part of the public API. It could either be that the documentation
206 -# For parts of the non-public API that is in a <em>private header
208 you choose to do so, you must document all elements in that header
213 This section describes all the Doxygen commands that will be used in the
221 in documentation. See the next section on \ref style for that. This
229 ended by an empty line, or if another command that defines a \link
230 commands_sections section \endlink is found. Note that if you use
231 commands that work on a paragraph and you split it over multiple lines
233 better), you will have to indent subsequent lines that belong to the
245 Tells Doxygen that the following section is going to be on the class as
248 This block is going to be about the function that corresponds to the
249 given declaration. Please note that the declaration is what you find in
255 declaration. This means basically that data members of a class should
273 If you have a look at the output that Doxygen generates, you can see that
274 there are recurring sections in the documentation. Documentation that
275 belongs to a certain section should be placed after a command that marks the
276 start of that section. All the commands take a paragraph as argument. A
277 paragraph ends with an empty line, or with a command that marks a new
278 section. Note that this list only shows the syntax of the commands. For the
297 There are also a number of things that can be used in pages and member
310 commands. There are commands that work on single words, commands that work
311 on longer phrases and commands that define blocks. Basically, the single
312 letter commands are commands that work on a the next word. If you need to
314 blocks of code or blocks of text that need to be in "typewriter" font, use
324 This can be used to refer to constants, or anything that needs to be in
329 these two commands will be put in a distinct block that stands out
343 Important to know is that a page is the complete length of the block, so
349 is the internal identifier that can be used in linking between pages (see
371 If you are creating multiple pages that are related, you will be able to
389 Groups of members are preceded by a block that describes what the group is
412 \c \\name command and a paragraph that gives a description. The header
415 The members that you want to belong to the group are between the group
422 There are some commands that don't fit into the categories above, but that
432 Sometimes there are some parts of the API that you don't want to be visible.
454 are two commands for that. The first one is \c \\ref, which enable you to
455 refer to pages, sections, etc. that you created yourself. The second one is
459 \\endlink. The first word between the two commands is the object that is
468 and pages, there are some general remarks that apply to all types of
474 - It means that every sentence should at least have a
485 try to find a balance. Read through documentation that's already been
488 down in such a way that it says everything it needs to. A proofreader
492 remarks that might interrupt the flow of the text, or that need to visually
493 stand out from the rest. Doxygen provides commands for paragraphs that
497 Notes on what to read first, or mistakes that may be made by beginners
503 separated so that it doesn't interrupt the main flow.
508 ambiguous. The difference between this and a warning is that
509 warnings warn about things that are the developers fault, and
510 attention blocks warn about things that might go wrong
512 - Used to warn for abuse of the API that might be caused by the way the
516 apply especially to new developers that aren't completely familiar
517 with the API and that might want to abuse it. For example, the
520 - Used to place references to other documentation that might not be
525 - Can also be used for useful hints or notes that somehow need to stand
528 - Remarks are small notes that would interrupt the flow of the text. For
529 example, if you in a text ignore a certain condition that is so
531 text to tell that you have been lying.
539 still under debate, but it does not change the requirement that a header
540 needs to be documented before the members of that header can be documented.
542 that describes the header. Examples:
560 file defines the BString class and some global operators. You can see that
563 that.
575 to include every item, it merely serves as a guiding principle that helps
579 what it is. For example, BDataIO: "Abstract interface for objects that
580 provide read and write access to data." Note that this description is
582 -# One or more paragraphs that give a broad overview of what the class can
586 sure that a developer in the first few paragraphs can judge if what he
588 -# One or more paragraphs that show how this class ties in with the rest
591 -# One or more paragraphs that give a concrete example or use case. Keep it
596 that might be of interest to the reader.
601 documentation page that connects the different points you want to make.
604 descriptions. If you want to do that, physically divide the members up in
619 means that for members, also the class name and the scope indicator (::)
620 should be present. Also note that this line doesn't have to adhere to
628 or function does, then you can add a few paragraphs that explain it in
633 command for that. For the description, use a short phrase such as "The
640 example, a method that returns a length (positive) or an error code
644 methods that do the opposite of this method, or methods that are
661 This section helps you document (member) variables and defines that define
663 a \c \#define macro that takes arguments, have a look at \ref style_members
666 They are a short phrase that mention what the variable contains. Example:
682 \c protected member variables, or global variables that have a certain
685 that is meant to be derived from, make sure that in the description of the
687 should make sure that the internal coherence of the data and code members of
692 depend on that constant. If the variable is meant to be changed by the
701 can give a description of the enumeration in a documentation block that
706 which can be done within code blocks that start with the \c \\var command.
707 Doxygen will know that it's an enumeration value, don't worry about mixups.
712 document the possible values there, then don't do that again for the
719 apply some general information that will be listed above the listing of the
720 members in that group. See the section \ref commands_grouping on how to
726 the rest of the words on that line will be used as the title. You should
730 should contain some quick notes on which of the members in that group to use
731 for what purpose. See it as a quick subdivision that a developer could use
733 describing the methods in detail though, that's what the member
741 range of operators that return a boolean value, secondly there are methods
742 that return an integer value, both case sensitive and case insensitive.
745 You might need these in case you have a sort routine that takes a generic