Re: [Doxygen-users] Documentation only.

[Scott H. <sc...@ha...>]

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

*/