i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

HaikuBook: add instructions for including INTERNAL documentation

Browse Source 
Change-Id: Ifb539a0a11d6aa9f496aa493d7a47a08016818be
Reviewed-on: https://review.haiku-os.org/c/haiku/+/3308
Reviewed-by: waddlesplash <[email protected]>
This commit is contained in:
Niels Sascha Reedijk
2020-10-11 15:46:06 +00:00
committed by waddlesplash
parent 2cb5a2c394
commit 5a6d68bbfa
1 changed files with 24 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/apidoc.dox
+24 -1
View File
@@ -1,6 +1,6 @@
/* /*
* Copyright 2007 Niels Sascha Reedijk. All rights reserved. * Copyright 2007 Niels Sascha Reedijk. All rights reserved.
* Copyright 2008-2013 Haiku, Inc. All rights reserved. * Copyright 2008-2013, 2020 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Authors: * Authors:
@@ -185,6 +185,29 @@
\note This is only for the source files and for you as documenter. It will \note This is only for the source files and for you as documenter. It will
not show up in the actual generated documentation! not show up in the actual generated documentation!
\subsection formalrequirements_internal Internal documentation
It is possible that there is documentation for parts of the API that are
not (yet) part of the public API. It could either be that the documentation
is part of the public header file (usually hidden behind a namespace like
\c BPrivate), or it is part of a private header file.
In case you are in the situation where you need to store private API docs,
you should put the entirety of the documentation in a conditional block,
with the \c INTERNAL identifier. You open the block with the command
<tt>//! \\cond INTERNAL</tt> and end the block with the command
<tt>//! \\endcond INTERNAL</tt>.
There are two different cases where you must or could use these blocks:
1. For non-public API of a <em>public header file</em>, you must always
add the classes and other elements to the documentation (even if they)
are placeholders, and put them in the conditional block.
2. For parts of the non-public API that is in a <em>private header
file</em>, you could put the documentation in a conditional block. If
you choose to do so, you must document all elements in that header
file.
\section commands Doxygen Commands \section commands Doxygen Commands
This section describes all the Doxygen commands that will be used in the This section describes all the Doxygen commands that will be used in the