Bug fixes and documentation improvements (r388:390)

src/action/action.h

@@ -2,6 +2,13 @@
  * \file   action.h
  * \brief  Built-in engine actions.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup action Actions
+ *
+ * The actions component contains the implementation of all of the built-in
+ * Premake actions, along with a few common support functions.
+ *
+ * @{
  */
 #if !defined(PREMAKE_ACTION_H)
 #define PREMAKE_ACTION_H
@@ -47,3 +54,4 @@ int  action_source_tree(Session sess, Project prj, Stream strm, ActionSourceCall
 
 
 #endif
+/** @} */

src/base/array.h

@@ -2,6 +2,13 @@
  * \file   array.h
  * \brief  Dynamic array object.
  * \author Copyright (c) 2007-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup array Array
+ * \ingroup  base
+ *
+ * A dynamic array class.
+ *
+ * @{
  */
 #if !defined(PREMAKE_ARRAY_H)
 #define PREMAKE_ARRAY_H
@@ -17,3 +24,4 @@ void  array_set(Array arr, int index, void* item);
 void  array_append(Array dest, Array src);
 
 #endif
+/** @} */

src/base/base.h

@@ -2,6 +2,11 @@
  * \file   base.h
  * \brief  Premake base library API.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup base Base
+ *
+ * This component defines all of the base classes required by the higher-level
+ * functions of Premake.
  */
 
 int base_tests();

src/base/buffers.h

@@ -2,6 +2,16 @@
  * \file   buffers.h
  * \brief  Shared working buffer system.
  * \author Copyright (c) 2007-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup buffers Buffers
+ * \ingroup  base
+ *
+ * A shared working buffer collection. A buffer can be requested from the system, filled,
+ * and passed around for a short period of time. This system allows transient string values
+ * to be returned from functions and immediately used without having to resort to
+ * full-blown string objects, and the ownership issues that would entail.
+ *
+ * @{
  */
 #if !defined(PREMAKE_BUFFER_H)
 #define PREMAKE_BUFFER_H
@@ -11,4 +21,5 @@ extern const int BUFFER_SIZE;
 char* buffers_next(void);
 
 #endif
+/** @} */
 

src/base/cstr.h

@@ -2,6 +2,13 @@
  * \file   cstr.h
  * \brief  C string handling.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup cstr C Strings
+ * \ingroup  base
+ *
+ * Functions to handle C strings (zero-terminated byte arrays).
+ *
+ * @{
  */
 #if !defined(PREMAKE_CSTR_H)
 #define PREMAKE_CSTR_H
@@ -13,3 +20,4 @@ char* cstr_format(const char* format, ...);
 int   cstr_starts_with(const char* str, const char* expected);
 
 #endif
+/** @} */

src/base/dir.h

@@ -2,6 +2,13 @@
  * \file   dir.h
  * \brief  Directory handling.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup dir Directory Management
+ * \ingroup  base
+ *
+ * Directory management functions.
+ *
+ * @{
  */
 #if !defined(PREMAKE_DIR_H)
 #define PREMAKE_DIR_H
@@ -12,3 +19,4 @@ char* dir_get_current(void);
 int   dir_set_current(const char* path);
 
 #endif
+/** @} */

src/base/error.h

@@ -2,6 +2,13 @@
  * \file   error.h
  * \brief  Application-wide error reporting.
  * \author Copyright (c) 2007-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup array Array
+ * \ingroup  base
+ *
+ * Application-wide error reporting.
+ *
+ * @{
  */
 #if !defined(PREMAKE_ERROR_H)
 #define PREMAKE_ERROR_H
@@ -11,3 +18,4 @@ const char* error_get(void);
 void        error_set(const char* message, ...);
 
 #endif
+/** @} */

src/base/guid.h

@@ -2,6 +2,13 @@
  * \file   guid.h
  * \brief  GUID creation and validation.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup guid GUIDs
+ * \ingroup  base
+ *
+ * GUID creation and validation functions.
+ *
+ * @{
  */
 #if !defined(PREMAKE_GUID_H)
 #define PREMAKE_GUID_H
@@ -10,3 +17,4 @@ const char* guid_create();
 int         guid_is_valid(const char* value);
 
 #endif
+/** @} */

src/base/path.h

@@ -2,6 +2,13 @@
  * \file   path.h
  * \brief  Path handling.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup path Path
+ * \ingroup  base
+ *
+ * Path manipulation functions.
+ *
+ * @{
  */
 #if !defined(PREMAKE_PATH_H)
 #define PREMAKE_PATH_H
@@ -19,3 +26,4 @@ char* path_relative(const char* base, const char* target);
 char* path_translate(const char* path, const char* sep);
 
 #endif
+/** @} */

src/base/stream.h

@@ -2,6 +2,13 @@
  * \file   stream.h
  * \brief  Output stream handling.
  * \author Copyright (c) 2007-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup stream Streams
+ * \ingroup  base
+ *
+ * An output stream class.
+ *
+ * @{
  */
 #if !defined(PREMAKE_STREAM_H)
 #define PREMAKE_STREAM_H
@@ -27,3 +34,4 @@ int    stream_writeline(Stream strm, const char* value, ...);
 int    stream_writeline_strings(Stream strm, Strings strs, const char* start, const char* prefix, const char* postfix, const char* infix);
 
 #endif
+/** @} */

src/base/string.h

@@ -2,6 +2,13 @@
  * \file   string.h
  * \brief  Dynamic string handling.
  * \author Copyright (c) 2007-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup string Strings
+ * \ingroup  base
+ *
+ * A dynamic string class.
+ *
+ * @{
  */
 #if !defined(PREMAKE_STRING_H)
 #define PREMAKE_STRING_H
@@ -13,3 +20,4 @@ void        string_destroy(string str);
 const char* string_cstr(string str);
 
 #endif
+/** @} */

src/base/strings.h

@@ -2,6 +2,13 @@
  * \file   strings.h
  * \brief  A dynamic array of C strings.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup strings String Collection
+ * \ingroup  base
+ *
+ * A dynamic array of C strings.
+ *
+ * @{
  */
 #if !defined(PREMAKE_STRINGS_H)
 #define PREMAKE_STRINGS_H
@@ -18,3 +25,4 @@ void        strings_set(Strings strs, int index, const char* item);
 int         strings_size(Strings strs);
 
 #endif
+/** @} */

src/host/host.h

@@ -2,6 +2,13 @@
  * \file   host.h
  * \brief  Main executable API.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup host Host
+ *
+ * The "host" part of the application, which is responsible for parsing the command
+ * line arguments, and the overall flow of the application. 
+ *
+ * @{
  */
 #if !defined(PREMAKE_HOST_H)
 #define PREMAKE_HOST_H
@@ -33,3 +40,4 @@ int  host_show_help(Session sess);
 int  host_tests(void);
 
 #endif
+/** @} */

src/platform/platform.h

@@ -2,6 +2,12 @@
  * \file   platform.h
  * \brief  Platform abstraction API.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup platform Platform
+ *
+ * Platform abstraction; primarily file system and directory management. 
+ *
+ * @{
  */
 #if !defined(PREMAKE_PLATFORM_H)
 #define PREMAKE_PLATFORM_H
@@ -79,3 +85,4 @@ void platform_set(enum Platform id);
 
 
 #endif
+/** @} */

src/project/fields.h

@@ -2,6 +2,9 @@
  * \file   fields.h
  * \brief  Project object fields enumeration and handling.
  * \author Copyright (c) 2007-2008 Jason Perkins and the Premake project
+ *
+ * \addtogroup project
+ * @{
  */
 #if !defined(PREMAKE_FIELDS_H)
 #define PREMAKE_FIELDS_H
@@ -50,3 +53,4 @@ void        fields_set_value(Fields fields, int index, const char* value);
 void        fields_set_values(Fields fields, int index, Strings values);
 
 #endif
+/* @} */

src/project/project.h

@@ -2,6 +2,12 @@
  * \file   project.h
  * \brief  Project objects API.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \defgroup project Project Objects
+ *
+ * Project objects: solutions, projects, and configurations.
+ *
+ * @{
  */
 #if !defined(PREMAKE_PROJECT_H)
 #define PREMAKE_PROJECT_H
@@ -54,3 +60,4 @@ void        project_set_values(Project prj, enum ProjectField field, Strings val
 int         project_tests(void);
 
 #endif
+/** @} */

src/project/solution.h

@@ -2,6 +2,9 @@
  * \file   solution.h
  * \brief  The Solution class, representing the top-level container for projects.
  * \author Copyright (c) 2002-2008 Jason Perkins and the Premake project
+ *
+ * \addtogroup project
+ * @{
  */
 #if !defined(PREMAKE_SOLUTION_H)
 #define PREMAKE_SOLUTION_H
@@ -51,3 +54,4 @@ void        solution_set_value(Solution sln, enum SolutionField field, const cha
 
 
 #endif
+/** @} */

src/script/script.h

@@ -2,6 +2,12 @@
  * \file   script.h
  * \brief  The project scripting engine.
  * \author Copyright (c) 2008 Jason Perkins and the Premake project
+ *
+ * \defgroup script Scripting Engine
+ *
+ * The project scripting engine.
+ *
+ * @{
  */
 #if !defined(PREMAKE_SCRIPT_H)
 #define PREMAKE_SCRIPT_H
@@ -20,3 +26,4 @@ int         script_tests(void);
 int         script_unload(Script script, Array slns);
 
 #endif
+/** @} */

src/script/tests/script_tests.cpp

@@ -13,7 +13,7 @@ extern "C" {
 
 
 /**
- * \brief   Run the suite of project scripting engine automated tests.
+ * Run the suite of project scripting engine automated tests.
  * \returns OKAY if all tests completed successfully.
  */
 int script_tests()

src/session/session.c

@@ -303,8 +303,7 @@ int session_unload(Session sess)
 
 
 /**
- * Make sure that all required objects and values have been defined by the
- * project script.
+ * Make sure that all required objects and values have been defined by the project script.
  * \param   sess      The session to validate.
  * \param   features  The features (language, kind, etc.) supported by the current action.
  * \returns OKAY if the session is valid.