diff --git a/agent-audio/src/AlsaAudio.h b/agent-audio/src/AlsaAudio.h
index 4864c073..8550cb87 100644
--- a/agent-audio/src/AlsaAudio.h
+++ b/agent-audio/src/AlsaAudio.h
@@ -54,7 +54,7 @@ YCPBoolean alsaSetMute(int card, const string& channel_name, bool value);
 YCPValue alsaGetMute(int card, const string& channel_name);
 
 /**
- * getChannels- list of available channels for card #id
+ * getChannels- list of available channels for the card
  * @param card card id
  *
  */
diff --git a/agent-audio/src/OSSAudio.cc b/agent-audio/src/OSSAudio.cc
index 8a32ba41..cd792bbb 100644
--- a/agent-audio/src/OSSAudio.cc
+++ b/agent-audio/src/OSSAudio.cc
@@ -63,18 +63,6 @@ int ossDevice(const string channel) {
     }
 }
 
-/**
- * @builtin SCR (`Write (.volume, integer volume)) -> bool
- * @builtin SCR (`Write (.volume.N, integer volume)) -> bool
- *
- * Set a master volume. If called with just volume, /dev/mixer
- * is used, otherwise /dev/mixerN is used as a device.
- *
- * This call returns true on success and false, if it fails.
- *
- * @example SCR (`Write (.volume, 50)) -> true
- * @example SCR (`Write (.volume.1, 50)) -> false
- */
 YCPBoolean ossSetVolume(const string card, const string channel, const int value) {
 
     string mixerfile = "/dev/mixer";
@@ -126,18 +114,6 @@ YCPBoolean ossSetVolume(const string card, const string channel, const int value
     return YCPBoolean (true);
 }
 
-/**
- * @builtin SCR (`Read (.volume)) -> integer
- * @builtin SCR (`Read (.volume.N)) -> integer
- *
- * Read a master volume. If called with just volume, /dev/mixer
- * is used, otherwise /dev/mixerN is used as a device.
- *
- * This call returns the volume on success and -1, if it fails.
- *
- * @example SCR (`Read (.volume)) -> 50
- * @example SCR (`Read (.volume.1)) -> -1
- */
 YCPValue ossGetVolume(const string card, const string channel) {
 
     string mixerfile = "/dev/mixer";
diff --git a/agent-audio/src/OSSAudio.h b/agent-audio/src/OSSAudio.h
index bd929d40..005296bd 100644
--- a/agent-audio/src/OSSAudio.h
+++ b/agent-audio/src/OSSAudio.h
@@ -17,18 +17,34 @@ using std::string;
 using std::vector;
 using std::map;
 
-/** 
- *  volume setting
+/**
+ * Set a master volume. If called with just volume, /dev/mixer
+ * is used, otherwise /dev/mixerN is used as a device.
+ *
+ * This call returns true on success and false, if it fails.
+ *
  *  @param card card id (default if empty)
  *  @param channel name eg. "Master" ("Master" if empty)
  *  @param value volume 0..100
+ *
+ * @example
+ *   SCR (`Write (.volume, 50)) -> true
+ *   SCR (`Write (.volume.1, 50)) -> false
  */
 YCPBoolean ossSetVolume(const string card, const string channel, const int value);
 
 /**
- * volume reading
+ * Read a master volume. If called with just volume, /dev/mixer
+ * is used, otherwise /dev/mixerN is used as a device.
+ *
+ * This call returns the volume on success and -1, if it fails.
+ *
  * @param card card id (default if empty)
  * @param channel channel name (Master if empty)
+ *
+ * @example
+ *   SCR (`Read (.volume)) -> 50
+ *   SCR (`Read (.volume.1)) -> -1
  */
 YCPValue ossGetVolume(const string card, const string channel);