Prikryl,Petr wrote:
> Angela Stazzone wrote...
>
>> And should I use a special suffix for these kind of files?
>
> The documentation-only files are used also for creating
> Doxygen's documentation. Have a look at doc subdirectory
> inside the Doxygen directory. The files use the .doc extension,
> but it does not matter. You can give it whatever extension,
> but the input files have to be determined via options
> inside your Doxyfile.
The technique I've been using is to put a "Readme.txt" file in the same
folder containing the Doxyfile (and then I add "*.txt" or "Readme.txt"
to the input file list in the Doxyfile). Not everyone here is using
Doxygen, but it's pretty easy to put together descriptions that format
well with Doxygen, yet are human-readable -- especially since Doxygen is
really good about automatically defining hyperlinks where it can. The
Readme.txt file contains the Doxygen @mainpage directive and provides
overview information for the project, build/install instructions, and
anything else that seems appropriate for the main page.
That particular file name was chosen because when someone stumbles
across a file called "Readme.txt", they probably have a pretty good idea
what to find there.
The information before the "/*!" is not included in the extracted
documentation, so that's a good place to inform the reader that Doxygen
exists, where to find it, and how to use it to extract the documentation
for this project.
Here's an example of the Readme.txt file. I'm including it mainly to
demonstrate that it's pretty easy to have text that's both Human- and
Doxygen-readable.
Comments/suggestions/criticisms are welcome.
--------------------cut here-----------------------
The design documentation for this project is included as comments in
the code. The doxygen tool (http://www.doxygen.org/) can be used to
extract this documentation into either a browsable web or an RTF
document. The doxygen installers are available at
http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc.
Once you have doxygen installed, just run "doxygen" from this
directory. Then view either html\index.html or rtf\refman.rtf.
/*! \mainpage CPriority
\todo
Add references for Linux and Windows pages re: process
priority manipulation.
\section ref References
\section intro Introduction
This class provides a simple, platform independent way for Windows or
Linux process to adjust their priority.
\subsection usage Usage
Say you have an application program whose priority you want to
lower. You'd do something like this:
<pre>
CPriority::TheInstance().AdjustPriority("Low");
</pre>
\section nt_vs_linux NT vs. Linux
Under Windows NT, you can't alter the priority of a process direct;
rather you specify a priority class (Low, Medium, High, Realtime).
Linux doesn't support these priority classes, but lets you specify
a maximum priority (-20..+20, the lower the number, the higher the
priority). In an attempt to provide comparable functionality in a
comparable way, the parameter to AdjustPriority is one of the
following values:
- "Low",
- "Medium", or
- "High"
For a Windows NT process, this is mapped directly to a priority
class. For Linux, "Low" = +10, "Medium" = 0, and "High" = -10.
Note that for Linux, only the superuser is allowed to raise a
process priority (lower number).
\section unit_testing CPriority Unit Testing (TEST.EXE)
The unit test for CPriority is defined in test.cpp. See comments in
that file for more information.
\section errors When Things Go Wrong
etc. etc. etc.
\todo
Test on Linux
*/
|
