Begin documenting machine config macros (nw)

src/emu/mconfig.h

@@ -1,12 +1,13 @@
 // license:BSD-3-Clause
 // copyright-holders:Aaron Giles
-/***************************************************************************
+/***************************************************************************/
+/**
+  * @file mconfig.h
+  * @defgroup MACHINE_CONFIG Machine configuration macros and functions
+  * @{
+  */
+/***************************************************************************/
 
-    mconfig.h
-
-    Machine configuration macros and functions.
-
-***************************************************************************/
 
 #pragma once
 
@@ -81,26 +82,52 @@ private:
 };
 
 
+//*************************************************************************/
+/** @name Machine config start/end macros */
+//*************************************************************************/
 
-//**************************************************************************
+/**
-//  MACHINE CONFIG MACROS
+ @def MACHINE_CONFIG_NAME(_name)
-//**************************************************************************
+ Returns the internal name for the machine config.
-
+ @param _name name of desired config
-// start/end tags for the machine driver
+ @hideinitializer
+ */
 #define MACHINE_CONFIG_NAME(_name) construct_machine_config_##_name
 
+/**
+ @def MACHINE_CONFIG_START(_name, _class)
+ Begins a new machine config.
+ @param _name name of this config
+ @param _class driver_device class for this config
+ @hideinitializer
+ */
 #define MACHINE_CONFIG_START(_name, _class) \
 ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t *owner, device_t *device) \
 { \
 	devcb_base *devcb = NULL; \
 	(void)devcb; \
 	if (owner == NULL) owner = config.device_add(NULL, "root", &driver_device_creator<_class>, 0);
+
+/**
+ @def MACHINE_CONFIG_FRAGMENT(_name)
+ Begins a partial machine_config that can only be included in another "root" machine_config. This is also used for machine_configs that are specified as part of a device.
+ @param _name name of this config fragment
+ @hideinitializer
+*/
 #define MACHINE_CONFIG_FRAGMENT(_name) \
 ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t *owner, device_t *device) \
 { \
 	devcb_base *devcb = NULL; \
 	(void)devcb; \
 	assert(owner != NULL);
+
+/**
+ @def MACHINE_CONFIG_DERIVED(_name, _base)
+ Begins a machine_config that is derived from another machine_config.
+ @param _name name of this config
+ @param _base name of the parent config
+ @hideinitializer
+*/
 #define MACHINE_CONFIG_DERIVED(_name, _base) \
 ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t *owner, device_t *device) \
 { \
@@ -108,6 +135,15 @@ ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t
 	(void)devcb; \
 	owner = MACHINE_CONFIG_NAME(_base)(config, owner, device); \
 	assert(owner != NULL);
+
+/**
+@def MACHINE_CONFIG_DERIVED_CLASS(_name, _base, _class)
+Begins a machine_config that is derived from another machine_config that can specify an alternate driver_device class
+@param _name name of this config
+@param _base name of the parent config
+@param _class name of the alternate driver_device class
+@hideinitializer
+*/
 #define MACHINE_CONFIG_DERIVED_CLASS(_name, _base, _class) \
 ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t *owner, device_t *device) \
 { \
@@ -115,14 +151,32 @@ ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t
 	(void)devcb; \
 	if (owner == NULL) owner = config.device_add(NULL, "root", &driver_device_creator<_class>, 0); \
 	owner = MACHINE_CONFIG_NAME(_base)(config, owner, device);
+
+/**
+@def MACHINE_CONFIG_END
+Ends a machine_config.
+@hideinitializer
+*/
 #define MACHINE_CONFIG_END \
 	return owner; \
 }
 
-// use this to declare external references to a machine driver
+//*************************************************************************/
+/** @name Standalone machine config macros */
+//*************************************************************************/
+
+/**
+@def MACHINE_CONFIG_EXTERN(_name)
+References an external machine config.
+@param _name Name of the machine config to reference
+@hideinitializer
+*/
 #define MACHINE_CONFIG_EXTERN(_name) \
 	extern device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t *owner, device_t *device)
 
+//*************************************************************************/
+/** @name Core machine config options */
+//*************************************************************************/
 
 // importing data from other machine drivers
 #define MCFG_FRAGMENT_ADD(_name) \
@@ -160,3 +214,4 @@ ATTR_COLD device_t *MACHINE_CONFIG_NAME(_name)(machine_config &config, device_t
 	device = config.device_find(owner, _tag);
 
 #endif  /* __MCONFIG_H__ */
+    /** @} */