summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorrubidium <rubidium@openttd.org>2011-05-01 20:04:09 +0000
committerrubidium <rubidium@openttd.org>2011-05-01 20:04:09 +0000
commit428044e0335e0ff3cfd2fd3ef86e024e389e5057 (patch)
treeb6a551838c5f5ed272ce6b9984cb7d81986283e7
parent5a620d1c6592057b500f0889eef8949dc1e95e4b (diff)
downloadopenttd-428044e0335e0ff3cfd2fd3ef86e024e389e5057.tar.xz
(svn r22407) -Document: the "root" driver related stuff
-rw-r--r--src/driver.cpp22
-rw-r--r--src/driver.h37
2 files changed, 55 insertions, 4 deletions
diff --git a/src/driver.cpp b/src/driver.cpp
index 8cab88fad..448320c83 100644
--- a/src/driver.cpp
+++ b/src/driver.cpp
@@ -31,6 +31,12 @@ char *_ini_musicdriver; ///< The music driver a stored in the configuration
char *_ini_blitter; ///< The blitter as stored in the configuration file.
+/**
+ * Get a string parameter the list of parameters.
+ * @param parm The parameters.
+ * @param name The parameter name we're looking for.
+ * @return The parameter value.
+ */
const char *GetDriverParam(const char * const *parm, const char *name)
{
size_t len;
@@ -49,11 +55,24 @@ const char *GetDriverParam(const char * const *parm, const char *name)
return NULL;
}
+/**
+ * Get a boolean parameter the list of parameters.
+ * @param parm The parameters.
+ * @param name The parameter name we're looking for.
+ * @return The parameter value.
+ */
bool GetDriverParamBool(const char * const *parm, const char *name)
{
return GetDriverParam(parm, name) != NULL;
}
+/**
+ * Get an integer parameter the list of parameters.
+ * @param parm The parameters.
+ * @param name The parameter name we're looking for.
+ * @param def The default value if the parameter doesn't exist.
+ * @return The parameter value.
+ */
int GetDriverParamInt(const char * const *parm, const char *name, int def)
{
const char *p = GetDriverParam(parm, name);
@@ -173,6 +192,9 @@ void DriverFactoryBase::RegisterDriver(const char *name, Driver::Type type, int
/**
* Build a human readable list of available drivers, grouped by type.
+ * @param p The buffer to write to.
+ * @param last The last element in the buffer.
+ * @return The end of the written buffer.
*/
char *DriverFactoryBase::GetDriversInfo(char *p, const char *last)
{
diff --git a/src/driver.h b/src/driver.h
index 0718ffdad..10a6863bc 100644
--- a/src/driver.h
+++ b/src/driver.h
@@ -20,10 +20,19 @@ const char *GetDriverParam(const char * const *parm, const char *name);
bool GetDriverParamBool(const char * const *parm, const char *name);
int GetDriverParamInt(const char * const *parm, const char *name, int def);
+/** A driver for communicating with the user. */
class Driver {
public:
+ /**
+ * Start this driver.
+ * @param parm Parameters passed to the driver.
+ * @return NULL if everything went okay, otherwise an error message.
+ */
virtual const char *Start(const char * const *parm) = 0;
+ /**
+ * Stop this driver.
+ */
virtual void Stop() = 0;
virtual ~Driver() { }
@@ -37,32 +46,50 @@ public:
DT_END, ///< Helper for iteration
};
+ /**
+ * Get the name of this driver.
+ * @return The name of the driver.
+ */
virtual const char *GetName() const = 0;
};
DECLARE_POSTFIX_INCREMENT(Driver::Type)
+/** Base for all driver factories. */
class DriverFactoryBase {
private:
- Driver::Type type;
- const char *name;
- int priority;
+ Driver::Type type; ///< The type of driver.
+ const char *name; ///< The name of the drivers of this factory.
+ int priority; ///< The priority of this factory.
- typedef std::map<const char *, DriverFactoryBase *, StringCompare> Drivers;
+ typedef std::map<const char *, DriverFactoryBase *, StringCompare> Drivers; ///< Type for a map of drivers.
+ /**
+ * Get the map with drivers.
+ */
static Drivers &GetDrivers()
{
static Drivers &s_drivers = *new Drivers();
return s_drivers;
}
+ /**
+ * Get the active driver for the given type.
+ * @param type The type to get the driver for.
+ * @return The active driver.
+ */
static Driver **GetActiveDriver(Driver::Type type)
{
static Driver *s_driver[3] = { NULL, NULL, NULL };
return &s_driver[type];
}
+ /**
+ * Get the driver type name.
+ * @param type The type of driver to get the name of.
+ * @return The name of the type.
+ */
static const char *GetDriverTypeName(Driver::Type type)
{
static const char * const driver_type_name[] = { "music", "sound", "video" };
@@ -95,11 +122,13 @@ public:
/**
* Get a nice description of the driver-class.
+ * @return The description.
*/
virtual const char *GetDescription() = 0;
/**
* Create an instance of this driver-class.
+ * @return The instance.
*/
virtual Driver *CreateInstance() = 0;
};