commands: cosmetic changes mostly to m_property.h

The Doxygen-style documentation comments were nothing but bloat.

Also move mp_property_do() and mp_property_print() to command.h, where
they should belong, and fix their argument types. m_property.c/h is
supposed to be generic, while command.h provides declarations specific
to the mplayer core.

5 files changed, 94 insertions, 136 deletions

diff --git a/command.c b/command.c
index 6db4310f46..1b61846205 100644
--- a/command.c
+++ b/command.c
@@ -491,8 +491,6 @@ static int mp_property_metadata(m_option_t *prop, int action, void *arg,
     if (!demuxer)
         return M_PROPERTY_UNAVAILABLE;
 
-    m_property_action_t *ka;
-    char *meta;
     static const m_option_t key_type =
     {
         "metadata", NULL, CONF_TYPE_STRING, 0, 0, 0, NULL
@@ -505,9 +503,10 @@ static int mp_property_metadata(m_option_t *prop, int action, void *arg,
         *(char ***)arg = slist;
         return M_PROPERTY_OK;
     }
-    case M_PROPERTY_KEY_ACTION:
-        ka = arg;
-        if (!(meta = demux_info_get(demuxer, ka->key)))
+    case M_PROPERTY_KEY_ACTION: {
+        struct m_property_action *ka = arg;
+        char *meta = demux_info_get(demuxer, ka->key);
+        if (!meta)
             return M_PROPERTY_UNKNOWN;
         switch (ka->action) {
         case M_PROPERTY_GET:
@@ -518,6 +517,7 @@ static int mp_property_metadata(m_option_t *prop, int action, void *arg,
             return M_PROPERTY_OK;
         }
     }
+    }
     return M_PROPERTY_NOT_IMPLEMENTED;
 }
 
@@ -1495,12 +1495,13 @@ static char *translate_legacy_property(void *talloc_ctx, const char *name)
     return new_name ? new_name : (char *)name;
 }
 
-int mp_property_do(const char *name, int action, void *val, void *ctx)
+int mp_property_do(const char *name, int action, void *val,
+                   struct MPContext *ctx)
 {
     return m_property_do(mp_properties, name, action, val, ctx);
 }
 
-char *mp_property_print(const char *name, void *ctx)
+char *mp_property_print(const char *name, struct MPContext *ctx)
 {
     char *ret = NULL;
     if (mp_property_do(name, M_PROPERTY_PRINT, &ret, ctx) <= 0)
@@ -1646,8 +1647,6 @@ static const char *property_error_string(int error_value)
         return "NOT_IMPLEMENTED";
     case M_PROPERTY_UNKNOWN:
         return "PROPERTY_UNKNOWN";
-    case M_PROPERTY_DISABLED:
-        return "DISABLED";
     }
     return "UNKNOWN";
 }
diff --git a/command.h b/command.h
index 1367fa88e4..df419c8e02 100644
--- a/command.h
+++ b/command.h
@@ -25,5 +25,8 @@ struct mp_cmd;
 void run_command(struct MPContext *mpctx, struct mp_cmd *cmd);
 char *property_expand_string(struct MPContext *mpctx, char *str);
 void property_print_help(void);
+int mp_property_do(const char* name, int action, void* val,
+                   struct MPContext *mpctx);
+char* mp_property_print(const char *name, struct MPContext *mpctx);
 
 #endif /* MPLAYER_COMMAND_H */
diff --git a/m_property.c b/m_property.c
index c53ef19d81..aebdde88ef 100644
--- a/m_property.c
+++ b/m_property.c
@@ -38,17 +38,17 @@ static int do_action(const m_option_t *prop_list, const char *name,
 {
     const char *sep;
     const m_option_t *prop;
-    m_property_action_t ka;
-    int r;
     if ((sep = strchr(name, '/')) && sep[1]) {
         int len = sep - name;
         char base[len + 1];
         memcpy(base, name, len);
         base[len] = 0;
         prop = m_option_list_find(prop_list, base);
-        ka.key = sep + 1;
-        ka.action = action;
-        ka.arg = arg;
+        struct m_property_action ka = {
+            .key = sep + 1,
+            .action = action,
+            .arg = arg,
+        };
         action = M_PROPERTY_KEY_ACTION;
         arg = &ka;
     } else
@@ -56,7 +56,7 @@ static int do_action(const m_option_t *prop_list, const char *name,
     if (!prop)
         return M_PROPERTY_UNKNOWN;
     int (*control)(const m_option_t*, int, void*, void*) = prop->p;
-    r = control(prop, action, arg, ctx);
+    int r = control(prop, action, arg, ctx);
     if (action == M_PROPERTY_GET_TYPE && r < 0) {
         *(const m_option_t **)arg = prop;
         return M_PROPERTY_OK;
diff --git a/m_property.h b/m_property.h
index cca624b6db..99ab05ad62 100644
--- a/m_property.h
+++ b/m_property.h
@@ -21,145 +21,101 @@
 
 #include "m_option.h"
 
-/// \defgroup Properties
-///
-/// Properties provide an interface to query and set the state of various
-/// things in MPlayer. The API is based on the \ref Options API like the
-/// \ref Config, but instead of using variables, properties use an ioctl like
-/// function. The function is used to perform various actions like get and set
-/// (see \ref PropertyActions).
-///@{
-
-/// \file
-
-/// \defgroup PropertyActions Property actions
-/// \ingroup Properties
-///@{
-
-/// Get the current value.
-/** \param arg Pointer to a variable of the right type.
- */
-#define M_PROPERTY_GET         0
-
-/// Get a string representing the current value.
-/** Set the variable to a newly allocated string or NULL.
- *  \param arg Pointer to a char* variable.
- */
-#define M_PROPERTY_PRINT       1
-
-/// Set a new value.
-/** The variable is updated to the value actually set.
- *  \param arg Pointer to a variable of the right type.
- */
-#define M_PROPERTY_SET         2
-
-/// Set a new value from a string.
-/** \param arg String containing the value.
- */
-#define M_PROPERTY_PARSE       3
-
-/// Get a string containg a parsable representation.
-/** Set the variable to a newly allocated string or NULL.
- *  \param arg Pointer to a char* variable.
- */
-#define M_PROPERTY_TO_STRING   6
-
-/// Pass down an action to a sub-property.
-#define M_PROPERTY_KEY_ACTION  7
-
-/// Get a m_option describing the property.
-#define M_PROPERTY_GET_TYPE    8
-
-// Switch the property up/down by a given value.
-// arg: (double) value to add to the property
-#define M_PROPERTY_SWITCH 9
-
-///@}
-
-/// \defgroup PropertyActionsArg Property actions argument type
-/// \ingroup Properties
-/// \brief  Types used as action argument.
-///@{
-
-/// Argument for \ref M_PROPERTY_KEY_ACTION
-typedef struct {
+enum mp_property_action {
+    // Get the property type. This defines the fundamental data type read from
+    // or written to the property.
+    // If unimplemented, the m_option entry that defines the property is used.
+    //  arg: const m_option**
+    M_PROPERTY_GET_TYPE,
+
+    // Get the current value.
+    //  arg: pointer to a variable of the type according to the property type
+    M_PROPERTY_GET,
+
+    // Set a new value. The property wrapper will make sure that only valid
+    // values are set (e.g. according to the property type's min/max range).
+    // If unimplemented, the property is read-only.
+    //  arg: pointer to a variable of the type according to the property type
+    M_PROPERTY_SET,
+
+    // Get human readable string representing the current value.
+    // If unimplemented, the property wrapper uses the property type as
+    // fallback.
+    //  arg: char**
+    M_PROPERTY_PRINT,
+
+    // Switch the property up/down by a given value.
+    // If unimplemented, the property wrapper uses the property type as
+    // fallback.
+    //  arg: double* (value to add to the property)
+    M_PROPERTY_SWITCH,
+
+    // Set a new value from a string. The property wrapper parses this using the
+    // parse function provided by the property type.
+    // Can't be overridden by property implementations.
+    //  arg: char*
+    M_PROPERTY_PARSE,
+
+    // Get a string containing a parsable representation.
+    // Can't be overridden by property implementations.
+    //  arg: char**
+    M_PROPERTY_TO_STRING,
+
+    // Pass down an action to a sub-property.
+    // arg: struct m_property_action*
+    M_PROPERTY_KEY_ACTION,
+};
+
+// Argument for M_PROPERTY_KEY_ACTION
+struct m_property_action {
     const char* key;
     int action;
     void* arg;
-} m_property_action_t;
-
-///@}
-
-/// \defgroup PropertyActionsReturn Property actions return code
-/// \ingroup Properties
-/// \brief  Return values for the control function.
-///@{
-
-/// Returned on success.
-#define M_PROPERTY_OK                1
-
-/// Returned on error.
-#define M_PROPERTY_ERROR             0
-
-/// \brief Returned when the property can't be used, for example something about
-/// the subs while playing audio only
-#define M_PROPERTY_UNAVAILABLE      -1
+};
 
-/// Returned if the requested action is not implemented.
-#define M_PROPERTY_NOT_IMPLEMENTED  -2
+enum mp_property_return {
+    // Returned on success.
+    M_PROPERTY_OK = 1,
 
-/// Returned when asking for a property that doesn't exist.
-#define M_PROPERTY_UNKNOWN          -3
+    // Returned on error.
+    M_PROPERTY_ERROR = 0,
 
-/// Returned when the action can't be done (like setting the volume when edl mute).
-#define M_PROPERTY_DISABLED         -4
+    // Returned when the property can't be used, for example video related
+    // properties while playing audio only.
+    M_PROPERTY_UNAVAILABLE = -1,
 
-///@}
+    // Returned if the requested action is not implemented.
+    M_PROPERTY_NOT_IMPLEMENTED = -2,
 
-/// \ingroup Properties
-/// \brief Property action callback.
-typedef int(*m_property_ctrl_f)(const m_option_t* prop,int action,void* arg,void *ctx);
+    // Returned when asking for a property that doesn't exist.
+    M_PROPERTY_UNKNOWN = -3,
+};
 
-/// Do an action on a property.
-/** \param prop_list The list of properties.
- *  \param prop The path of the property.
- *  \param action See \ref PropertyActions.
- *  \param arg Argument, usually a pointer to the data type used by the property.
- *  \return See \ref PropertyActionsReturn.
- */
-int m_property_do(const m_option_t* prop_list, const char* prop,
+// Access a property.
+// action: one of m_property_action
+// ctx: opaque value passed through to property implementation
+// returns: one of mp_property_return
+int m_property_do(const struct m_option* prop_list, const char* property_name,
                   int action, void* arg, void *ctx);
 
-/// Print a list of properties.
+// Print a list of properties.
 void m_properties_print_help_list(const m_option_t* list);
 
-/// Expand a property string.
-/** This function allows to print strings containing property values.
+// Expand a property string.
+/* This function allows to print strings containing property values.
  *  ${NAME} is expanded to the value of property NAME or an empty
  *  string in case of error. $(NAME:STR) expand STR only if the property
  *  NAME is available.
- *
- *  \param prop_list An array of \ref m_option describing the available
- *                   properties.
- *  \param str The string to expand.
- *  \return The newly allocated expanded string.
  */
-char* m_properties_expand_string(const m_option_t* prop_list,char* str, void *ctx);
-
-// Helpers to use MPlayer's properties
+char* m_properties_expand_string(const struct m_option* prop_list, char* str,
+                                 void *ctx);
 
-/// Do an action with an MPlayer property.
-int mp_property_do(const char* name,int action, void* val, void *ctx);
-
-/// Get the value of a property as a string suitable for display in an UI.
-char* mp_property_print(const char *name, void* ctx);
-
-int m_property_int_ro(const m_option_t* prop, int action, void* arg, int var);
-int m_property_float_ro(const m_option_t* prop, int action, void* arg,
+// Trivial helpers for implementing properties.
+int m_property_int_ro(const struct m_option* prop, int action, void* arg,
+                      int var);
+int m_property_float_ro(const struct m_option* prop, int action, void* arg,
                         float var);
-int m_property_double_ro(const m_option_t* prop, int action, void* arg,
+int m_property_double_ro(const struct m_option* prop, int action, void* arg,
                          double var);
 
-///@}
-
 #endif /* MPLAYER_M_PROPERTY_H */
diff --git a/screenshot.c b/screenshot.c
index a6313d01da..7fb5fd9507 100644
--- a/screenshot.c
+++ b/screenshot.c
@@ -27,7 +27,7 @@
 #include "talloc.h"
 #include "screenshot.h"
 #include "mp_core.h"
-#include "m_property.h"
+#include "command.h"
 #include "bstr.h"
 #include "mp_msg.h"
 #include "path.h"