small documentation format fixes

11 files changed, 28 insertions, 32 deletions

diff --git a/libopie2/opiecore/device/odevice.cpp b/libopie2/opiecore/device/odevice.cpp
index b5ae4e5..8b64c41 100644
--- a/libopie2/opiecore/device/odevice.cpp
+++ b/libopie2/opiecore/device/odevice.cpp
@@ -325,30 +325,30 @@ bool ODevice::setDisplayStatus ( bool on )
 #else
     if (( fd = ::open ( "/dev/fb0", O_RDWR )) >= 0 ) {
 #endif
         res = ( ::ioctl ( fd, FBIOBLANK, on ? VESA_NO_BLANKING : VESA_POWERDOWN ) == 0 );
         ::close ( fd );
     }
     return res;
 }
 
 /**
 * This sets the display brightness
 *
-* @param p The brightness to be set on a scale from 0 to 255
+* @param b The brightness to be set on a scale from 0 to 255
 * @return success or failure
 */
-bool ODevice::setDisplayBrightness ( int p)
+bool ODevice::setDisplayBrightness ( int b)
 {
-        Q_UNUSED( p )
+        Q_UNUSED( b )
     return false;
 }
 
 /**
  * 
  * @return Returns the number of steppings on the brightness slider
  * in the Light-'n-Power settings. Values smaller zero and bigger
  * than 255 do not make sense.
  *
  * \sa QSlider::setLineStep
  * \sa QSlider::setPageStep
  */
diff --git a/libopie2/opiecore/oconfig.h b/libopie2/opiecore/oconfig.h
index ab95dc3..05a1a25 100644
--- a/libopie2/opiecore/oconfig.h
+++ b/libopie2/opiecore/oconfig.h
@@ -118,25 +118,25 @@ private:
  * is unwished.
  *
  * @author Matthias Kalle Dalheimer <Kalle@kde.org>
  * @version $Id$
  * @see OConfig
  */
 
 class OConfigGroupSaver
 {
   public:
     /**
      * Constructor.
-     * Create the object giving a @config object and a @a group to become
+     * Create the object giving a OConfig object and a @a group to become
      * the current group.
      */
     OConfigGroupSaver( OConfig* config, QString group ) :_config(config), _oldgroup(config->group() )
         { _config->setGroup( group ); }
 
     OConfigGroupSaver( OConfig* config, const char *group ) :_config(config), _oldgroup(config->group())
         { _config->setGroup( group ); }
 
     OConfigGroupSaver( OConfig* config, const QCString &group ) : _config(config), _oldgroup(config->group())
         { _config->setGroup( group ); }
     /**
      * Destructor.
diff --git a/libopie2/opiecore/odebug.h b/libopie2/opiecore/odebug.h
index 21a6c26..18dc09e 100644
--- a/libopie2/opiecore/odebug.h
+++ b/libopie2/opiecore/odebug.h
@@ -407,55 +407,55 @@ class ondbgstream {
 
 private:
     class Private;
     Private *d;
 };
 
 /*======================================================================================
  * related functions
  *======================================================================================*/
 
 /**
  * Does nothing.
- * @param a stream
+ * @param s stream
  * @return the given @p s
  */
 inline ondbgstream& endl( ondbgstream & s) { return s; }
 /**
  * Does nothing.
- * @param a stream
+ * @param s stream
  * @return the given @p s
  */
 inline ondbgstream& flush( ondbgstream & s) { return s; }
 inline ondbgstream& perror( ondbgstream & s) { return s; }
 
 /**
  * Returns a debug stream. You can use it to print debug
  * information.
  * @param area an id to identify the output, 0 for default
  */
 odbgstream odDebug(int area = 0);
 odbgstream odDebug(bool cond, int area = 0);
 /**
  * Returns a backtrace.
  * @param levels the number of levels (-1 for unlimited) of the backtrace
  * @return a backtrace
  */
 QString odBacktrace(int levels = -1);
 /**
  * Returns a dummy debug stream. The stream does not print anything.
  * @param area an id to identify the output, 0 for default
  * @see odDebug()
  */
-inline ondbgstream ondDebug(int = 0) { return ondbgstream(); }
+inline ondbgstream ondDebug(int area = 0) { return ondbgstream(); }
 inline ondbgstream ondDebug(bool , int  = 0) { return ondbgstream(); }
 inline QString ondBacktrace() { return QString::null; }
 inline QString ondBacktrace(int) { return QString::null; }
 
 /**
  * Returns a warning stream. You can use it to print warning
  * information.
  * @param area an id to identify the output, 0 for default
  */
 odbgstream odWarning(int area = 0);
 odbgstream odWarning(bool cond, int area = 0);
 /**
diff --git a/libopie2/opiecore/okeyconfigmanager.cpp b/libopie2/opiecore/okeyconfigmanager.cpp
index 891cda7..48546bd 100644
--- a/libopie2/opiecore/okeyconfigmanager.cpp
+++ b/libopie2/opiecore/okeyconfigmanager.cpp
@@ -88,25 +88,25 @@ int OKeyPair::modifier()const {
  * @param key The Keycode to set
  *
  * @see keycode()
  * @see Qt::Key
  */
 void OKeyPair::setKeycode( int key ) {
     m_key = key;
 }
 
 /**
  * Set the modifier key
  *
- * @param the Modifier key
+ * @param mod the Modifier key
  * @see Qt::ButtonState
  * @see modifier()
  */
 void OKeyPair::setModifier( int mod ) {
     m_mod = mod;
 }
 
 /**
  * Return  an OKeyPair for the Return Key without any modifier.
  */
 OKeyPair OKeyPair::returnKey() {
     return OKeyPair( Qt::Key_Return, 0 );
diff --git a/libopie2/opiecore/okeyfilter.h b/libopie2/opiecore/okeyfilter.h
index d183641..1871247 100644
--- a/libopie2/opiecore/okeyfilter.h
+++ b/libopie2/opiecore/okeyfilter.h
@@ -72,29 +72,29 @@ protected:
      * @param aFilter a filter to remove
      * @see remHandler
      */
     virtual void remPreHandler(QWSServer::KeyboardFilter*aFilter)=0;
 
 public:
     virtual ~OKeyFilter();
     /**
      * Append filter to the secondary list.
      * @param aFilter a filter to append
      * @see addPreHandler
      */
-    virtual void addHandler(QWSServer::KeyboardFilter*)=0;
+    virtual void addHandler(QWSServer::KeyboardFilter *aFilter)=0;
     /**
      * Remove the specified filter from list and give back ownership.
      * @param aFilter a filter to remove
      * @see remPreHandler
      */
-    virtual void remHandler(QWSServer::KeyboardFilter*)=0;
+    virtual void remHandler(QWSServer::KeyboardFilter *aFilter)=0;
 
     /**
      * Returns a handler to an instance of OKeyFilter
      * @return a pointer to a working OKeyFilter
      */
     static OKeyFilter*inst();
 };
 
 }
 }
diff --git a/libopie2/opiecore/opluginloader.cpp b/libopie2/opiecore/opluginloader.cpp
index ec19fa0..2a6e369 100644
--- a/libopie2/opiecore/opluginloader.cpp
+++ b/libopie2/opiecore/opluginloader.cpp
@@ -514,25 +514,25 @@ QString OGenericPluginLoader::unlibify( const QString& str ) {
     return st.left( st.findRev( ".so" ) );
 #endif
 }
 
 /**
  * @internal
  *
  * \brief method to return available plugins. Internal and for reeimplementations
  *
  *Return a List of Plugins for a dir and add positions and remove disabled.
  * If a plugin is on the excluded list assign position -2
  *
- * @param dir The dir to look in
+ * @param _dir The dir to look in
  * @param sorted Should positions be read?
  * @param disabled Remove excluded from the list
  */
 OPluginItem::List OGenericPluginLoader::plugins( const QString& _dir, bool sorted, bool disabled )const {
 #ifdef Q_OS_MACX
     QDir dir( _dir, "lib*.dylib" );
 #else
     QDir dir( _dir, "lib*.so" );
 #endif
 
 
     OPluginItem::List lst;
@@ -672,25 +672,24 @@ OPluginLoader::OPluginLoader( const QString& name,  bool sorted )
  * @see OGenericPluginLoader::~OGenericPluginLoader
  */
 OPluginLoader::~OPluginLoader() {
 }
 
 /**
  * \brief C'Tor using a OGenericPluginLoader
  * The C'tor. Pass your OGenericPluginLoader to manage
  * OGenericPluginLoader::allAvailable plugins.
  *
  *
  * @param loader A Pointer to your OGenericPluginLoader
- * @param name The name
  */
 OPluginManager::OPluginManager(  OGenericPluginLoader* loader)
     : m_loader( loader ), m_isSorted( false )
 {
 }
 
 /**
  * \brief Overloaded c'tor using a List of Plugins and a type name
  * Overloaded Constructor to work with a 'Type' of plugins
  * and a correspending list of those. In this case calling load
  * is a no operation.
  *
@@ -748,25 +747,25 @@ OPluginItem::List OPluginManager::managedPlugins()const {
  */
 void OPluginManager::setPosition( const OPluginItem& item) {
     replace( item );
 }
 
 /**
  * \brief Enable the item specified as argument
  *
  * This will make sure that OPluginItem::setEnabled is called and then will replace
  * the item with one that matches name and path internally.
  * @see setPosition
  *
- * @param the Item to enable
+ * @param item the Item to enable
  */
 void OPluginManager::enable(  const OPluginItem& item ) {
     setEnabled( item, true );
 }
 
 /**
  * \brief disable the Item.
  *
  * Disable the OPluginItem. Same applies as in
  * @see setPosition and @see enable
  *
  * @param item Item to disable
diff --git a/libopie2/opiecore/oprocess.h b/libopie2/opiecore/oprocess.h
index be1436c..ac6be98 100644
--- a/libopie2/opiecore/oprocess.h
+++ b/libopie2/opiecore/oprocess.h
@@ -45,25 +45,25 @@ _;:,     .>    :=|.         This program is free software; you can
 class QSocketNotifier;
 
 namespace Opie {
 namespace Core {
 namespace Internal {
 class OProcessController;
 class OProcessPrivate;
 }
 
 /**
  * Child process invocation, monitoring and control.
  *
- * @sect General usage and features
+ * @par General usage and features
  *
  *This class allows a KDE and OPIE application to start child processes without having
  *to worry about UN*X signal handling issues and zombie process reaping.
  *
  *@see KProcIO
  *
  *Basically, this class distinguishes three different ways of running
  *child processes:
  *
  *@li  OProcess::DontCare -- The child process is invoked and both the child
  *process and the parent process continue concurrently.
  *
@@ -101,25 +101,25 @@ class OProcessPrivate;
  *
  **proc << "my_executable";
  **proc << "These" << "are" << "the" << "command" << "line" << "args";
  *QApplication::connect(proc, SIGNAL(processExited(Opie::Core::OProcess *)),
  *                      pointer_to_my_object, SLOT(my_objects_slot(Opie::Core::OProcess *)));
  *proc->start();
  *</pre>
  *
  *This will start "my_executable" with the commandline arguments "These"...
  *
  *When the child process exits, the respective Qt signal will be emitted.
  *
- *@sect Communication with the child process
+ *@par Communication with the child process
  *
  *OProcess supports communication with the child process through
  *stdin/stdout/stderr.
  *
  *The following functions are provided for getting data from the child
  *process or sending data to the child's stdin (For more information,
  *have a look at the documentation of each function):
  *
  *@li bool @ref writeStdin(char  *buffer, int  buflen);
  *@li  -- Transmit data to the child process's stdin.
  *
  *@li bool @ref closeStdin();
@@ -129,25 +129,25 @@ class OProcessPrivate;
  *
  *@li bool @ref closeStdout();
  *@li -- Closes the child process's stdout.
  *Returns false if you try to close stdout for a process that has been started
  *without a communication channel to stdout.
  *
  *@li bool @ref closeStderr();
  *@li -- Closes the child process's stderr.
  *Returns false if you try to close stderr for a process that has been started
  *without a communication channel to stderr.
  *
  *
- *@sect QT signals:
+ *@par QT signals:
  *
  *@li void @ref receivedStdout(OProcess  *proc, char  *buffer, int  buflen);
  *@li  void @ref receivedStderr(OProcess  *proc, char  *buffer, int  buflen);
  *@li  -- Indicates that new data has arrived from either the
  *child process's stdout or stderr.
  *
  *@li  void @ref wroteStdin(OProcess  *proc);
  *@li  -- Indicates that all data that has been sent to the child process
  *by a prior call to @ref writeStdin() has actually been transmitted to the
  *client .
  *
  *@author Christian Czezakte e9025461@student.tuwien.ac.at
@@ -482,24 +482,25 @@ signals:
      **/
     void processExited( Opie::Core::OProcess *proc );
 
 
     /**
      * Emitted, when output from the child process has
      * been received on stdout.
      *
      *  To actually get
      * these signals, the respective communication link (stdout/stderr)
      * has to be turned on in @ref start().
      *
+     * @param proc The process
      * @param buffer The data received.
      * @param buflen The number of bytes that are available.
      *
      * You should copy the information contained in @p buffer to your private
      * data structures before returning from this slot.
      **/
     void receivedStdout( Opie::Core::OProcess *proc, char *buffer, int buflen );
 
     /**
      * Emitted when output from the child process has
      * been received on stdout.
      *
@@ -515,24 +516,25 @@ signals:
      * The data still has to be read from file descriptor @p fd.
      **/
     void receivedStdout( int fd, int &len );
 
 
     /**
      * Emitted, when output from the child process has
      * been received on stderr.
      * To actually get
      * these signals, the respective communication link (stdout/stderr)
      * has to be turned on in @ref start().
      *
+     * @param proc The process
      * @param buffer The data received.
      * @param buflen The number of bytes that are available.
      *
      * You should copy the information contained in @p buffer to your private
      * data structures before returning from this slot.
     */
     void receivedStderr( Opie::Core::OProcess *proc, char *buffer, int buflen );
 
     /**
      * Emitted after all the data that has been
      * specified by a prior call to @ref writeStdin() has actually been
      * written to the child process.
diff --git a/libopie2/opieui/oimageeffect.h b/libopie2/opieui/oimageeffect.h
index 4f86d5b..4422741 100644
--- a/libopie2/opieui/oimageeffect.h
+++ b/libopie2/opieui/oimageeffect.h
@@ -210,25 +210,25 @@ public:
      * @param percent Percent value. Use a negative value to dim.
      * @param channel Which channel(s) should be modified
      * @return The @p image, provided for convenience.
      */
     static QImage& channelIntensity(QImage &image, float percent,
                                     RGBComponent channel);
 
     /**
      * Fade an image to a certain background color.
      *
      * The number of colors will not be changed.
      *
-     * @param image The QImage to process.
+     * @param img The QImage to process.
      * @param val The strength of the effect. 0 <= val <= 1.
      * @param color The background color.
      * @return Returns the @ref image(), provided for convenience.
      */
     static QImage& fade(QImage &img, float val, const QColor &color);
 
 
     /**
      * This recolors a pixmap. The most dark color will become color a,
      * the most bright one color b, and in between.
      *
      * @param image A QImage to process.
@@ -299,25 +299,25 @@ public:
      *
      * @author Daniel M. Duley (mosfet)
      * @param image The QImage to process.
      * @param c A contrast value between -255 to 255.
      * @return The @ref image(), provided for convenience.
      */
     static QImage& contrast(QImage &image, int c);
 
     /**
      * Dither an image using Floyd-Steinberg dithering for low-color
      * situations.
      *
-     * @param image The QImage to process.
+     * @param img The QImage to process.
      * @param palette The color palette to use
      * @param size The size of the palette
      * @return Returns the @ref image(), provided for convenience.
      */
     static QImage& dither(QImage &img, const QColor *palette, int size);
 
     /**
      * Calculate the image for a selected image, for instance a selected icon
      * on the desktop.
      * @param img the QImage to select
      * @param col the selected color, usually from QColorGroup::highlight().
      */
@@ -521,25 +521,25 @@ public:
      * effect some pixels may be "empty". This value is used for those pixels.
      * @return The swirled image. The original is not changed.
      */
      static QImage swirl(QImage &src, double degrees=50.0, unsigned int background =
                          0xFFFFFFFF);
 
      /**
       * Modifies the pixels along a sine wave.
       *
       * @author Daniel M. Duley (mosfet)
       * @param src The QImage to process.
       * @param amplitude The amplitude of the sine wave.
-      * @param wavelength The frequency of the sine wave.
+      * @param frequency The frequency of the sine wave.
       * @return The new image. The original is not changed.
       */
      static QImage wave(QImage &src, double amplitude=25.0, double frequency=150.0,
                         unsigned int background = 0xFFFFFFFF);
 
 private:
 
     /**
      * Helper function to fast calc some altered (lighten, shaded) colors
      *
      */
     static unsigned int lHash(unsigned int c);
diff --git a/libopie2/opieui/opixmapeffect.h b/libopie2/opieui/opixmapeffect.h
index b780f9f..85a1e25 100644
--- a/libopie2/opieui/opixmapeffect.h
+++ b/libopie2/opieui/opixmapeffect.h
@@ -143,34 +143,29 @@ public:
      *
      * @param pixmap The pixmap to process.
      * @param ca Color a.
      * @param cb Color b.
      * @param ncols The number of colors to use. The image will be
      * dithered to this depth. Pass zero to prevent dithering.
      * @return The @ref pixmap(), provided for convenience.
      */
     static OPixmap pattern(const OPixmap& pixmap, QSize size,
                    const QColor &ca, const QColor &cb, int ncols=8);
 
     /**
-     * Recolors a pixmap.
-     *
-     * The most dark color will become color a,
-     * the most bright one color b, and in between.
+     * Fades a pixmap to a certain color.
      *
      * @param pixmap The pixmap to process.
-     * @param ca Color a.
-     * @param cb Color b.
-     * @param ncols The number of colors to use. Pass zero to prevent
-     * dithering.
+     * @param val The strength of the effect. 0 <= val <= 1.
+     * @param color The color to blend to.
      * @return Returns the @ref pixmap(), provided for convenience.
      */
     static OPixmap& fade(OPixmap& pixmap, double val, const QColor &color);
 
     /**
      * Converts a pixmap to grayscale.
      *
      * @param pixmap The pixmap to process.
      * @param fast Set to @p true in order to use a faster but non-photographic
      * quality algorithm. Appropriate for things such as toolbar icons.
      * @return Returns the @ref pixmap(), provided for convenience.
      */
diff --git a/libopie2/qt3/opieui/ocombobox.h b/libopie2/qt3/opieui/ocombobox.h
index 4e35b61..3f60f54 100644
--- a/libopie2/qt3/opieui/ocombobox.h
+++ b/libopie2/qt3/opieui/ocombobox.h
@@ -44,25 +44,25 @@
 #include <opie2/ocompletionbase.h>
 
 /* FORWARDS */
 
 class QListBoxItem;
 class QPopupMenu;
 class OCompletionBox;
 typedef QString OURL;
 
 /**
  * A combined button, line-edit and a popup list widget.
  *
- * @sect Detail
+ * @par Detail
  *
  * This widget inherits from @ref QComboBox and implements
  * the following additional functionalities:  a completion
  * object that provides both automatic and manual text
  * completion as well as text rotation features, configurable
  * key-bindings to activate these features, and a popup-menu
  * item that can be used to allow the user to set text completion
  * modes on the fly based on their preference.
  *
  * To support these new features OComboBox also emits a few
  * more additional signals as well.  The main ones are the
  * @ref completion( const QString& ) and @ref textRotation( KeyBindingType )
@@ -88,25 +88,25 @@ typedef QString OURL;
  * can be overriden locally by invoking @ref OCompletionBase::setKeyBinding().
  * The values can easily be reverted back to the default setting, by simply
  * calling @ref useGlobalSettings(). An alternate method would be to default
  * individual key-bindings by usning @ref setKeyBinding() with the default
  * second argument.
  *
  * Note that if this widget is not editable ( i.e. select-only ), then only
  * one completion mode, @p CompletionAuto, will work.  All the other modes are
  * simply ignored.  The @p CompletionAuto mode in this case allows you to
  * automatically select an item from the list by trying to match the pressed
  * keycode with the first letter of the enteries in the combo box.
  *
- * @sect Useage
+ * @par Usage
  *
  * To enable the basic completion feature:
  *
  * <pre>
  * OComboBox *combo = new OComboBox( true, this, "mywidget" );
  * OCompletion *comp = combo->completionObject();
  * // Connect to the return pressed signal - optional
  * connect(combo,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&));
  * </pre>
  *
  * To use your own completion object:
  *
diff --git a/libopie2/qt3/opieui/olineedit.h b/libopie2/qt3/opieui/olineedit.h
index ecfca27..db3d7ef 100644
--- a/libopie2/qt3/opieui/olineedit.h
+++ b/libopie2/qt3/opieui/olineedit.h
@@ -41,25 +41,25 @@
 
 #include <opie2/ocompletion.h>
 #include <opie2/ocompletionbase.h>
 
 class QPopupMenu;
 
 class OCompletionBox;
 typedef QString KURL; //class KURL;
 
 /**
  * An enhanced QLineEdit widget for inputting text.
  *
- * @sect Detail
+ * @par Detail
  *
  * This widget inherits from @ref QLineEdit and implements the following
  * additional functionalities: q completion object that provides both
  * automatic and manual text completion as well as multiple match iteration
  * features, configurable key-bindings to activate these features and a
  * popup-menu item that can be used to allow the user to set text completion
  * modes on the fly based on their preference.
  *
  * To support these new features OLineEdit also emits a few more
  * additional signals.  These are: @ref completion( const QString& ),
  * textRotation( KeyBindingType ), and @ref returnPressed( const QString& ).
  * The completion signal can be connected to a slot that will assist the
@@ -86,25 +86,25 @@ typedef QString KURL; //class KURL;
  * The values can easily be reverted back to the default setting, by simply
  * calling @ref useGlobalSettings(). An alternate method would be to default
  * individual key-bindings by usning @ref setKeyBinding() with the default
  * second argument.
  *
  * NOTE that if the @p EchoMode for this widget is set to something other
  * than @p QLineEdit::Normal, the completion mode will always be defaulted
  * to @ref PGlobalSettings::CompletionNone.  This is done purposefully to guard
  * against protected entries such as passwords being cached in @ref OCompletion's
  * list. Hence, if the @p EchoMode is not @ref QLineEdit::Normal, the completion
  * mode is automatically disabled.
  *
- * @sect Useage
+ * @par Usage
  *
  * To enable the basic completion feature :
  *
  * <pre>
  * OLineEdit *edit = new OLineEdit( this, "mywidget" );
  * OCompletion *comp = edit->completionObject();
  * // Fill the completion object with a list of possible matches
  * QStringList list;
  * list << "mickeyl@handhelds.org" << "mickey@tm.informatik.uni-frankfurt.de>" << "mickey@Vanille.de";
  * comp->setItems( list );
  * // Connect to the return pressed signal (optional)
  * connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&));
@@ -116,25 +116,25 @@ typedef QString KURL; //class KURL;
  * <pre>
  * OLineEdit *edit = new OLineEdit( this,"mywidget" );
  * KURLCompletion *comp = new KURLCompletion();
  * edit->setCompletionObject( comp );
  * // Connect to the return pressed signal - optional
  * connect(edit,SIGNAL(returnPressed(const QString&)),comp,SLOT(addItem(const QString&));
  * </pre>
  *
  * Note that you have to either delete the allocated completion object
  * when you don't need it anymore, or call
  * setAutoDeleteCompletionObject( true );
  *
- * @sect Miscellaneous function calls :
+ * @par Miscellaneous function calls :
  *
  * <pre>
  * // Tell the widget not to handle completion and
  * // iteration internally.
  * edit->setHandleSignals( false );
  * // Set your own completion key for manual completions.
  * edit->setKeyBinding( OCompletionBase::TextCompletion, Qt::End );
  * // Hide the context (popup) menu
  * edit->setContextMenuEnabled( false );
  * // Temporarly disable signal emitions
  * // (both completion & iteration signals)
  * edit->disableSignals();