GNOME.org
 

[retro-gtk/build-doc: 7/11] Give basic documentation to public sections

commit e1377602f63fdad19f694a23d88ed25619428c71
Author: Adrien Plazas <kekun plazas laposte net>
Date:   Fri Apr 17 15:43:00 2020 +0200

    Give basic documentation to public sections
    
    This will make what will become public sections in the documentation to
    look decent enough for a first version.

 retro-gtk/retro-controller-iterator.c |  7 +++++++
 retro-gtk/retro-controller.c          |  7 +++++++
 retro-gtk/retro-core-descriptor.c     |  7 +++++++
 retro-gtk/retro-core-view.c           |  7 +++++++
 retro-gtk/retro-core.c                |  7 +++++++
 retro-gtk/retro-key-joypad-mapping.c  |  7 +++++++
 retro-gtk/retro-log.c                 |  9 +++++++++
 retro-gtk/retro-module-iterator.c     |  7 +++++++
 retro-gtk/retro-module-query.c        |  7 +++++++
 retro-gtk/retro-option-iterator.c     |  7 +++++++
 retro-gtk/retro-option.c              |  7 +++++++
 retro-gtk/retro-pixbuf.c              |  9 +++++++++
 retro-gtk/retro-pixdata.c             | 15 +++++++++++++++
 retro-gtk/retro-video-filter.c        |  7 +++++++
 shared/retro-controller-codes.c       |  7 +++++++
 shared/retro-controller-type.c        |  7 +++++++
 shared/retro-input.c                  | 16 ++++++++++++++++
 shared/retro-memory-type.c            |  7 +++++++
 shared/retro-rumble-effect.c          |  7 +++++++
 19 files changed, 154 insertions(+)
---
diff --git a/retro-gtk/retro-controller-iterator.c b/retro-gtk/retro-controller-iterator.c
index 82b4a4c..fc046e2 100644
--- a/retro-gtk/retro-controller-iterator.c
+++ b/retro-gtk/retro-controller-iterator.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-controller-iterator
+ * @short_description: An object iterating through the controllers plugged into a RetroCore
+ * @title: RetroControllerIterator
+ * @See_also: #RetroController, #RetroCore
+ */
+
 #include "retro-controller-iterator-private.h"
 
 struct _RetroControllerIterator
diff --git a/retro-gtk/retro-controller.c b/retro-gtk/retro-controller.c
index 9dae85b..b682694 100644
--- a/retro-gtk/retro-controller.c
+++ b/retro-gtk/retro-controller.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-controller
+ * @short_description: An interface representing an input controller
+ * @title: RetroController
+ * @See_also: #retro-controller-codes
+ */
+
 #include "retro-controller.h"
 
 G_DEFINE_INTERFACE (RetroController, retro_controller, G_TYPE_OBJECT);
diff --git a/retro-gtk/retro-core-descriptor.c b/retro-gtk/retro-core-descriptor.c
index 5e3dae2..e6380a4 100644
--- a/retro-gtk/retro-core-descriptor.c
+++ b/retro-gtk/retro-core-descriptor.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-core-descriptor
+ * @short_description: An object describing the capabilities and requirements of a Libretro core
+ * @title: RetroCoreDescriptor
+ * @See_also: #RetroCore
+ */
+
 #include "retro-core-descriptor.h"
 
 struct _RetroCoreDescriptor
diff --git a/retro-gtk/retro-core-view.c b/retro-gtk/retro-core-view.c
index 157ba23..4292beb 100644
--- a/retro-gtk/retro-core-view.c
+++ b/retro-gtk/retro-core-view.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-core-view
+ * @short_description: A widget to handle a core's inputs and outputs
+ * @title: RetroCoreView
+ * @See_also: #RetroCore, #RetroVideoFilter
+ */
+
 #include "retro-core-view.h"
 
 #include "retro-cairo-display-private.h"
diff --git a/retro-gtk/retro-core.c b/retro-gtk/retro-core.c
index e44719d..fe508b2 100644
--- a/retro-gtk/retro-core.c
+++ b/retro-gtk/retro-core.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-core
+ * @short_description: An object handling a Libretro core
+ * @title: RetroCore
+ * @See_also: #RetroCoreView
+ */
+
 #include "retro-core.h"
 
 #include <errno.h>
diff --git a/retro-gtk/retro-key-joypad-mapping.c b/retro-gtk/retro-key-joypad-mapping.c
index 09513d2..fc5b91a 100644
--- a/retro-gtk/retro-key-joypad-mapping.c
+++ b/retro-gtk/retro-key-joypad-mapping.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-key-joypad-mapping
+ * @short_description: An object mapping keyboard keys to joypad inputs
+ * @title: RetroKeyJoypadMapping
+ * @See_also: #RetroCoreView
+ */
+
 #include "retro-key-joypad-mapping.h"
 
 #include <linux/input-event-codes.h>
diff --git a/retro-gtk/retro-log.c b/retro-gtk/retro-log.c
index eea33f0..6ec1f1c 100644
--- a/retro-gtk/retro-log.c
+++ b/retro-gtk/retro-log.c
@@ -1,5 +1,14 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-log
+ * @short_description: Functions to log a Libretro core
+ * @title: RetroCore Logging Functions
+ * @See_also: #RetroCore
+ *
+ * Convenience functions to connect to the #RetroCore::log signal of #RetroCore.
+ */
+
 #include "retro-core.h"
 
 /**
diff --git a/retro-gtk/retro-module-iterator.c b/retro-gtk/retro-module-iterator.c
index 5f63a53..da29782 100644
--- a/retro-gtk/retro-module-iterator.c
+++ b/retro-gtk/retro-module-iterator.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-module-iterator
+ * @short_description: An object iterating through the available Libretro cores
+ * @title: RetroModuleIterator
+ * @See_also: #RetroCoreDescriptor, #RetroModuleQuery
+ */
+
 #include "retro-module-iterator.h"
 
 struct _RetroModuleIterator
diff --git a/retro-gtk/retro-module-query.c b/retro-gtk/retro-module-query.c
index abf8e6d..28dd8a3 100644
--- a/retro-gtk/retro-module-query.c
+++ b/retro-gtk/retro-module-query.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-module-query
+ * @short_description: An object to query the available Libretro cores
+ * @title: RetroModuleQuery
+ * @See_also: #RetroCoreDescriptor, #RetroModuleIterator
+ */
+
 #include "retro-module-query.h"
 
 #include "../retro-gtk-config.h"
diff --git a/retro-gtk/retro-option-iterator.c b/retro-gtk/retro-option-iterator.c
index 00865be..1986fde 100644
--- a/retro-gtk/retro-option-iterator.c
+++ b/retro-gtk/retro-option-iterator.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-option-iterator
+ * @short_description: An object iterating through the options of a #RetroCore
+ * @title: RetroOptionIterator
+ * @See_also: #RetroCore, #RetroOption
+ */
+
 #include "retro-option-iterator.h"
 
 struct _RetroOptionIterator
diff --git a/retro-gtk/retro-option.c b/retro-gtk/retro-option.c
index 488ff9b..57c0037 100644
--- a/retro-gtk/retro-option.c
+++ b/retro-gtk/retro-option.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-option
+ * @short_description: An object representing an option from a Libretro core
+ * @title: RetroOption
+ * @See_also: #RetroCore
+ */
+
 #include "retro-option-private.h"
 
 struct _RetroOption
diff --git a/retro-gtk/retro-pixbuf.c b/retro-gtk/retro-pixbuf.c
index 900417d..31f349a 100644
--- a/retro-gtk/retro-pixbuf.c
+++ b/retro-gtk/retro-pixbuf.c
@@ -1,5 +1,14 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-pixbuf
+ * @short_description: Functions for #GdkPixbuf
+ * @title: Pixbuf Functions
+ * @See_also: #GdkPixbuf, #RetroCoreView
+ *
+ * Convenience functions to handle the options of a #GdkPixbuf.
+ */
+
 #include "retro-pixbuf.h"
 #include <string.h>
 
diff --git a/retro-gtk/retro-pixdata.c b/retro-gtk/retro-pixdata.c
index ab82be2..4f1b04c 100644
--- a/retro-gtk/retro-pixdata.c
+++ b/retro-gtk/retro-pixdata.c
@@ -1,5 +1,20 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-pixdata
+ * @short_description: A structure holding the video output from a #RetroCore
+ * @title: RetroPixdata
+ * @See_also: #GdkPixbuf, #RetroCoreView
+ *
+ * The #RetroPixdata structure holds the internal representation of a
+ * #RetroCore's video output. To use the image, either convert it to a
+ * #GdkPixbuf via retro_pixdata_to_pixbuf() or load it as an OpenGL texture via
+ * retro_pixdata_load_gl_texture().
+ *
+ * The generated #GdkPixbuf will store the intended aspect-ratio, you can access
+ * it via retro_pixbuf_get_aspect_ratio().
+ */
+
 #include "retro-pixdata-private.h"
 
 #include <epoxy/gl.h>
diff --git a/retro-gtk/retro-video-filter.c b/retro-gtk/retro-video-filter.c
index dc86d7f..96cae67 100644
--- a/retro-gtk/retro-video-filter.c
+++ b/retro-gtk/retro-video-filter.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-video-filter
+ * @short_description: A video filter enumeration
+ * @title: RetroVideoFilter
+ * @See_also: #RetroCoreView
+ */
+
 #include "retro-video-filter.h"
 
 /**
diff --git a/shared/retro-controller-codes.c b/shared/retro-controller-codes.c
index 65769a3..acaea3f 100644
--- a/shared/retro-controller-codes.c
+++ b/shared/retro-controller-codes.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-controller-codes
+ * @short_description: Controller input codes and Linux convertion functions
+ * @title: RetroController Codes
+ * @See_also: #RetroController
+ */
+
 #include <linux/input-event-codes.h>
 #include "retro-controller-codes.h"
 
diff --git a/shared/retro-controller-type.c b/shared/retro-controller-type.c
index 22f48ac..5cfa19a 100644
--- a/shared/retro-controller-type.c
+++ b/shared/retro-controller-type.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-controller-type
+ * @short_description: A controller type enumeration
+ * @title: RetroControllerType
+ * @See_also: #RetroController
+ */
+
 #include "retro-controller-type.h"
 
 #include "retro-controller-codes.h"
diff --git a/shared/retro-input.c b/shared/retro-input.c
index 394b4bd..f60a025 100644
--- a/shared/retro-input.c
+++ b/shared/retro-input.c
@@ -1,5 +1,21 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-input
+ * @short_description: A structure representing a controller input
+ * @title: RetroInput
+ * @See_also: #RetroController, #RetroControllerType
+ *
+ * The #RetroInput structure represents an input from a controller, like a
+ * button, an axis, or a key.
+ *
+ * To know the represented input type, first check the input's controller type
+ * via retro_input_get_controller_type(), then use the accessor function
+ * matching it.
+ * E.g. if the controller type is %RETRO_CONTROLLER_TYPE_JOYPAD, you can know
+ * which joypad input type is represented via retro_input_get_joypad().
+ */
+
 #include "retro-input-private.h"
 
 G_DEFINE_BOXED_TYPE (RetroInput, retro_input, retro_input_copy, retro_input_free)
diff --git a/shared/retro-memory-type.c b/shared/retro-memory-type.c
index 29eb71a..8c1d9d3 100644
--- a/shared/retro-memory-type.c
+++ b/shared/retro-memory-type.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-memory-type
+ * @short_description: A memory type enumeration
+ * @title: RetroMemoryType
+ * @See_also: #RetroCore
+ */
+
 #include "retro-memory-type.h"
 
 GType
diff --git a/shared/retro-rumble-effect.c b/shared/retro-rumble-effect.c
index 8c01f89..4692e05 100644
--- a/shared/retro-rumble-effect.c
+++ b/shared/retro-rumble-effect.c
@@ -1,5 +1,12 @@
 // This file is part of retro-gtk. License: GPL-3.0+.
 
+/**
+ * SECTION:retro-rumble-effect
+ * @short_description: A rumble effect enumeration
+ * @title: RetroRumbleEffect
+ * @See_also: #RetroController
+ */
+
 #include "retro-rumble-effect.h"
 
 GType
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]