[dia] general: docs cleanups
- From: Zander <zbrown src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [dia] general: docs cleanups
- Date: Fri, 1 May 2020 02:36:09 +0000 (UTC)
commit 4ff02eaac794d68d3fb886ebd7d9f5c00a2109d4
Author: Zander Brown <zbrown gnome org>
Date: Fri May 1 03:05:05 2020 +0100
general: docs cleanups
app/display.c | 30 +++++++-------
lib/arrows.c | 3 +-
lib/dia_svg.c | 16 +-------
lib/element.c | 7 +++-
lib/geometry.h | 112 +++++++++++++++++++++++++++++++++++---------------
lib/message.c | 3 ++
lib/message.h | 44 ++++++++++----------
lib/object.c | 3 ++
lib/object.h | 69 +++++++++++++++++++++----------
lib/object_defaults.c | 25 ++++++-----
lib/parent.c | 5 +++
lib/textline.c | 39 ++++++++++++------
lib/textline.h | 29 ++++++-------
13 files changed, 239 insertions(+), 146 deletions(-)
---
diff --git a/app/display.c b/app/display.c
index b82fb5b3..d9d4358f 100644
--- a/app/display.c
+++ b/app/display.c
@@ -1359,36 +1359,38 @@ ddisplay_really_destroy (DDisplay *ddisp)
void
-ddisplay_set_title(DDisplay *ddisp, char *title)
+ddisplay_set_title (DDisplay *ddisp, char *title)
{
- if (ddisp->is_standalone_window)
+ if (ddisp->is_standalone_window) {
gtk_window_set_title (GTK_WINDOW (ddisp->shell), title);
- else
- {
+ } else {
GtkNotebook *notebook = g_object_get_data (G_OBJECT (ddisp->shell),
DIA_MAIN_NOTEBOOK);
/* Find the page with ddisp then set the label on the tab */
- gint num_pages = gtk_notebook_get_n_pages (notebook);
- gint num;
+ int num_pages = gtk_notebook_get_n_pages (notebook);
+ int num;
GtkWidget *page;
- for (num = 0 ; num < num_pages ; num++)
- {
+ for (num = 0 ; num < num_pages ; num++) {
page = gtk_notebook_get_nth_page (notebook,num);
- if (g_object_get_data (G_OBJECT (page), "DDisplay") == ddisp)
- {
+ if (g_object_get_data (G_OBJECT (page), "DDisplay") == ddisp) {
GtkLabel *label = g_object_get_data (G_OBJECT (page), "tab-label");
/* not using the passed in title here, because it may be too long */
- gchar *name = diagram_get_name(ddisp->diagram);
- gtk_label_set_text(label,name);
+ char *name = diagram_get_name (ddisp->diagram);
+
+ gtk_label_set_text (label,name);
+
g_clear_pointer (&name, g_free);
+
break;
}
}
/* now modify the application window title */
{
- const gchar *pname = g_get_prgname();
- gchar *fulltitle = g_strdup_printf ("%s - %s", title, pname ? pname : "Dia");
+ const char *pname = g_get_application_name ();
+ char *fulltitle = g_strdup_printf ("%s — %s", title, pname);
+
gtk_window_set_title (GTK_WINDOW (ddisp->shell), fulltitle);
+
g_clear_pointer (&fulltitle, g_free);
}
}
diff --git a/lib/arrows.c b/lib/arrows.c
index 6395ebdf..b4258917 100644
--- a/lib/arrows.c
+++ b/lib/arrows.c
@@ -2531,6 +2531,7 @@ save_arrow (ObjectNode obj_node,
arrow->width, ctx);
}
+
/**
* load_arrow:
* @obj_node: The XML node to load from.
@@ -2538,7 +2539,7 @@ save_arrow (ObjectNode obj_node,
* @type_attribute: the name of the attribute of the arrow type.
* @length_attribute: the name of the attribute of the arrow length.
* @width_attribute: the name of the attribte of the arrow width.
- * @ctx:
+ * @ctx: the current #DiaContext
*
* Load arrow information from three attributes.
*/
diff --git a/lib/dia_svg.c b/lib/dia_svg.c
index 6f34ba72..28fcb5a0 100644
--- a/lib/dia_svg.c
+++ b/lib/dia_svg.c
@@ -936,20 +936,8 @@ _path_arc_segment(GArray* points,
g_array_append_val(points, bez);
}
-/**
- * _path_arc:
- * @points:
- * @cpx:
- * @cpy:
- * @rx:
- * @ry:
- * @x_axis_rotation:
- * @large_arc_flag:
- * @sweep_flag:
- * @x:
- * @y:
- * @last_p2:
- *
+
+/*
* Parse an SVG description of a full arc.
*/
static void
diff --git a/lib/element.c b/lib/element.c
index dba889f0..cad03feb 100644
--- a/lib/element.c
+++ b/lib/element.c
@@ -517,10 +517,13 @@ element_destroy (Element *elem)
/**
* element_save:
- * @elem:
- * @obj_node:
+ * @elem: the #Element to save
+ * @obj_node: the #ObjectNode to save to
+ * @ctx: the current #DiaContent
*
* Save the element-specific parts of this element to XML.
+ *
+ * Since: dawn-of-time
*/
void
element_save (Element *elem, ObjectNode obj_node, DiaContext *ctx)
diff --git a/lib/geometry.h b/lib/geometry.h
index f5bb516b..ef0ce36c 100644
--- a/lib/geometry.h
+++ b/lib/geometry.h
@@ -77,39 +77,72 @@ G_BEGIN_DECLS
V y
*/
-/*! \brief A two dimensional position */
+
+/**
+ * Point:
+ * @x: horizontal
+ * @y: vertical
+ *
+ * A two dimensional position
+ *
+ * Since: dawn-of-time
+ */
struct _Point {
- double x; /*!< horizontal */
- double y; /*!< vertical */
+ double x;
+ double y;
};
+
/**
* DiaRectangle:
* @left: top left x co-ord
* @top: top left y co-ord
* @right: bottom right x co-ord
- * @button bottom right y co-ord
+ * @button: bottom right y co-ord
*
* A rectangle given by upper left and lower right corner
+ *
+ * Since: 0.98
*/
struct _DiaRectangle {
- double left; /*!< x1 */
- double top; /*!< y1 */
- double right; /*!< x2 */
- double bottom; /*!< y2 */
+ double left;
+ double top;
+ double right;
+ double bottom;
};
-/*! \brief A rectangle for fixed point e.g. pixel doubleinates */
+
+/**
+ * IntRectangle:
+ * @left: top left x co-ord
+ * @top: top left y co-ord
+ * @right: bottom right x co-ord
+ * @button: bottom right y co-ord
+ *
+ * A rectangle for fixed point e.g. pixel doubleinates
+ *
+ * Since: dawn-of-time
+ */
struct _IntRectangle {
- int left; /*!< x1 */
- int top; /*!< y1 */
- int right; /*!< x2 */
- int bottom; /*!< y2 */
+ int left;
+ int top;
+ int right;
+ int bottom;
};
-/*!
- * \brief BezPoint is a bezier point forming _Bezierline or _Beziergon
- * \ingroup ObjectParts
+
+/**
+ * BezPoint:
+ * @BEZ_MOVE_TO: move to point @p1
+ * @BEZ_LINE_TO: line to point @p1
+ * @BEZ_CURVE_TO: curve to point @p3 using @p1 and @p2 as control points
+ * @p1: main point in case of move or line-to, otherwise first control point
+ * @p2: second control point
+ * @p3: main point for 'true' bezier point
+ *
+ * #BezPoint is a bezier point forming #Bezierline or #Beziergon
+ *
+ * Since: dawn-of-time
*/
struct _BezPoint {
enum {
@@ -122,31 +155,42 @@ struct _BezPoint {
Point p3; /*!< main point for 'true' bezier point */
};
-/*!
- * \brief DiaMatrix used for affine transformation
+
+/**
+ * DiaMatrix:
*
- * The struct is intentionally binary compatible with cairo_matrix_t.
+ * #DiaMatrix used for affine transformation
*
- * \ingroup ObjectParts
+ * The struct is intentionally binary compatible with #cairo_matrix_t.
+ *
+ * Since: dawn-of-time
*/
struct _DiaMatrix {
- real xx; real yx;
- real xy; real yy;
- real x0; real y0;
+ double xx;
+ double yx;
+ double xy;
+ double yy;
+ double x0;
+ double y0;
};
-gboolean dia_matrix_is_identity (const DiaMatrix *matix);
+
+gboolean dia_matrix_is_identity (const DiaMatrix *matix);
gboolean dia_matrix_get_angle_and_scales (const DiaMatrix *m,
- real *a,
- real *sx,
- real *sy);
-void dia_matrix_set_angle_and_scales (DiaMatrix *m,
- real a,
- real sx,
- real sy);
-void dia_matrix_multiply (DiaMatrix *result, const DiaMatrix *a, const DiaMatrix *b);
-gboolean dia_matrix_is_invertible (const DiaMatrix *matrix);
-void dia_matrix_set_rotate_around (DiaMatrix *result, real angle, const Point *around);
+ double *a,
+ double *sx,
+ double *sy);
+void dia_matrix_set_angle_and_scales (DiaMatrix *m,
+ double a,
+ double sx,
+ double sy);
+void dia_matrix_multiply (DiaMatrix *result,
+ const DiaMatrix *a,
+ const DiaMatrix *b);
+gboolean dia_matrix_is_invertible (const DiaMatrix *matrix);
+void dia_matrix_set_rotate_around (DiaMatrix *result,
+ double angle,
+ const Point *around);
#define ROUND(x) ((int) floor((x)+0.5))
diff --git a/lib/message.c b/lib/message.c
index f68f2f6e..6667b8ed 100644
--- a/lib/message.c
+++ b/lib/message.c
@@ -268,6 +268,7 @@ message(const char *title, const char *format, ...)
/**
* message_notice:
* @format: the message
+ * @...: @format arguments
*
* Emit a message about something the user should be aware of.
* In the default GTK message system, this message will by default only
@@ -291,6 +292,7 @@ message_notice (const char *format, ...)
/**
* message_warning:
* @format: the message
+ * @...: @format arguments
*
* Emit a message about a possible danger.
* In the default GTK message system, this message can be made to only be
@@ -314,6 +316,7 @@ message_warning (const char *format, ...)
/**
* message_error:
* @format: the message
+ * @...: @format arguments
*
* Emit a message about an error.
* In the default GTK message system, this message is always shown.
diff --git a/lib/message.h b/lib/message.h
index 96aacc85..393cf583 100644
--- a/lib/message.h
+++ b/lib/message.h
@@ -15,8 +15,8 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
-#ifndef MESSAGE_H
-#define MESSAGE_H
+
+#pragma once
#include <stdarg.h>
@@ -28,26 +28,26 @@ enum ShowAgainStyle {
SUGGEST_NO_SHOW_AGAIN
};
-typedef void (*MessageInternal)(const char *title, enum ShowAgainStyle showAgain,
- char const *fmt,
- va_list args, va_list args2);
-
-void set_message_func(MessageInternal func);
-void message(const char *title, const char *format, ...) G_GNUC_PRINTF(2, 3);
-void message_notice(const char *format, ...) G_GNUC_PRINTF(1, 2);
-void message_warning(const char *format, ...) G_GNUC_PRINTF(1, 2);
-void message_error(const char *format, ...) G_GNUC_PRINTF(1, 2);
-
-void dia_log_message(const char *format, ...) G_GNUC_PRINTF(1, 2);
-void dia_log_message_enable (gboolean yes);
+typedef void (*MessageInternal) (const char *title,
+ enum ShowAgainStyle showAgain,
+ char const *fmt,
+ va_list args,
+ va_list args2);
+
+void set_message_func (MessageInternal func);
+void message (const char *title,
+ const char *format,
+ ...) G_GNUC_PRINTF (2, 3);
+void message_notice (const char *format,
+ ...) G_GNUC_PRINTF (1, 2);
+void message_warning (const char *format,
+ ...) G_GNUC_PRINTF (1, 2);
+void message_error (const char *format,
+ ...) G_GNUC_PRINTF (1, 2);
+void dia_log_message (const char *format,
+ ...) G_GNUC_PRINTF (1, 2);
+void dia_log_message_enable (gboolean yes);
/* also declared in dia_dirs.h, where I think it does not belong! --hb */
-const gchar *dia_message_filename (const gchar *filename);
+const char *dia_message_filename (const char *filename);
G_END_DECLS
-
-#endif /* MESSAGES_H */
-
-
-
-
-
diff --git a/lib/object.c b/lib/object.c
index b57b4905..8bfa365b 100644
--- a/lib/object.c
+++ b/lib/object.c
@@ -550,12 +550,15 @@ object_substitute (DiaObject *obj, DiaObject *subst)
return (ObjectChange*)change;
}
+
/**
* destroy_object_list:
* @list_to_be_destroyed: A of objects list to destroy. The list itself
* will also be freed.
*
* Destroy a list of objects by calling ops->destroy on each in turn.
+ *
+ * Since: dawn-of-time
*/
void
destroy_object_list (GList *list_to_be_destroyed)
diff --git a/lib/object.h b/lib/object.h
index 506f9648..28ffbcf3 100644
--- a/lib/object.h
+++ b/lib/object.h
@@ -213,12 +213,12 @@ void object_copy(DiaObject *from, DiaObject *to);
void object_save(DiaObject *obj, ObjectNode obj_node, DiaContext *ctx);
void object_load(DiaObject *obj, ObjectNode obj_node, DiaContext *ctx);
-GList *object_copy_list(GList *list);
+GList *object_copy_list (GList *list_orig );
ObjectChange* object_list_move_delta_r(GList *objects, Point *delta, gboolean affected);
ObjectChange* object_list_move_delta(GList *objects, Point *delta);
ObjectChange *object_substitute (DiaObject *obj, DiaObject *subst);
-void destroy_object_list(GList *list);
+void destroy_object_list (GList *list_to_be_destroyed);
void object_add_handle(DiaObject *obj, Handle *handle);
void object_add_handle_at(DiaObject *obj, Handle *handle, int pos);
void object_remove_handle(DiaObject *obj, Handle *handle);
@@ -373,8 +373,18 @@ struct _DiaObject {
GHashTable *meta;
};
-/*
- * \brief Vtable for _DiaObjectType
+
+/**
+ * DiaObjectType:
+ * @create: the #CreateFunc
+ * @load: the #LoadFunc
+ * @save: the #SaveFunc
+ * @get_defaults: the #GetDefaultsFunc
+ * @apply_defaults: the #ApplyDefaultsFunc
+ *
+ * Vtable for _DiaObjectType
+ *
+ * Since: dawn-of-time
*/
struct _ObjectTypeOps {
CreateFunc create;
@@ -382,37 +392,54 @@ struct _ObjectTypeOps {
SaveFunc save;
GetDefaultsFunc get_defaults;
ApplyDefaultsFunc apply_defaults;
+
+ /*< private >*/
+
/*
Unused places (for extension).
- These should be NULL for now. In the future they might be used.
+ These should be %NULL for now. In the future they might be used.
Then an older object will be binary compatible, because all new code
- checks if new ops are supported (!= NULL)
+ checks if new ops are supported (!= %NULL)
*/
void (*unused[10])(DiaObject *obj,...);
};
+
/*!
\brief _DiaObject factory
Structure so that the ObjectFactory can create objects
of unknown type. (Read in from a shared lib.)
*/
-struct _DiaObjectType {
-
- char *name; /*!< The type name should follow a pattern of '\<module\> - \<class\>' like "UML - Class" */
- int version; /*!< DiaObjects must be backward compatible, i.e. support possibly older versions formats */
-
- const char **pixmap; /*!< Also put a pixmap in the sheet_object.
- This one is used if not in sheet but in toolbar.
- Stored in xpm format */
- ObjectTypeOps *ops; /* pointer to the vtable */
-
- char *pixmap_file; /*!< fallback if pixmap is NULL */
- void *default_user_data; /*!< use this if no user data is specified in the .sheet file */
- const PropDescription *prop_descs; /*!< property descriptions */
- const PropOffset *prop_offsets; /*!< DiaObject struct offsets */
- gint flags; /*!< Various flags that can be set for this object, see defines above */
+/**
+ * DiaObjectType:
+ * @name: The type name should follow a pattern of '\<module\> - \<class\>'
+ * like "UML - Class"
+ * @version: #DiaObject s must be backward compatible, i.e. support possibly
+ * older versions formats
+ * @pixmap: Also put a pixmap in the sheet_object. This one is used if not
+ * in sheet but in toolbar. Stored in xpm format.
+ * @ops: Pointer to the vtable
+ * @pixmap_file: fallback if pixmap is %NULL
+ * @default_user_data: use this if no user data is specified in
+ * the .sheet file
+ * @prop_descs: Property descriptions
+ * @prop_offsets: #DiaObject struct offsets
+ * @flags: Various flags that can be set for this object, see defines above
+ *
+ * Since: dawn-of-time
+ */
+struct _DiaObjectType {
+ char *name;
+ int version;
+ const char **pixmap;
+ ObjectTypeOps *ops;
+ char *pixmap_file;
+ void *default_user_data;
+ const PropDescription *prop_descs;
+ const PropOffset *prop_offsets;
+ int flags;
};
/* base property stuff ... */
diff --git a/lib/object_defaults.c b/lib/object_defaults.c
index 9d20d386..a98de2b3 100644
--- a/lib/object_defaults.c
+++ b/lib/object_defaults.c
@@ -241,21 +241,24 @@ pdtpp_standard_or_defaults (const PropDescription *pdesc)
/**
* dia_object_default_create:
- * @param type The objects type
- * @param startpoint The left upper corner
- * @param user_data
- * @param handle1
- * @param handle2
- * @return A newly created object.
+ * @type: The objects type
+ * @startpoint: The left upper corner
+ * @user_data:
+ * @handle1:
+ * @handle2:
*
* Create an object respecting defaults if available
+ *
+ * Returns: A newly created object.
+ *
+ * Since: dawn-of-time
*/
DiaObject *
-dia_object_default_create (const DiaObjectType *type,
- Point *startpoint,
- void *user_data,
- Handle **handle1,
- Handle **handle2)
+dia_object_default_create (const DiaObjectType *type,
+ Point *startpoint,
+ void *user_data,
+ Handle **handle1,
+ Handle **handle2)
{
const DiaObject *def_obj;
DiaObject *obj;
diff --git a/lib/parent.c b/lib/parent.c
index d11073b1..517364f8 100644
--- a/lib/parent.c
+++ b/lib/parent.c
@@ -255,12 +255,17 @@ parent_point_extents(Point *point, DiaRectangle *extents)
extents->bottom = point->y;
}
+
/**
* parent_handle_extents:
+ * @obj: the #DiaObject
+ * @extents: the extend of the object
*
* the caller must provide the 'returned' rectangle,
* which is initialized to the biggest rectangle containing
* all the objects handles
+ *
+ * Since: dawn-of-time
*/
void
parent_handle_extents (DiaObject *obj, DiaRectangle *extents)
diff --git a/lib/textline.c b/lib/textline.c
index 691a0442..359a1312 100644
--- a/lib/textline.c
+++ b/lib/textline.c
@@ -201,11 +201,13 @@ text_line_get_descent(const TextLine *text_line)
* Returns: The amount (in diagram lengths) to shift the x positiion of
* rendering this such that it looks aligned when printed with x at the left.
* Always a positive number.
+ *
+ * Since: dawn-of-time
*/
-real
+double
text_line_get_alignment_adjustment (TextLine *text_line, Alignment alignment)
{
- text_line_cache_values(text_line);
+ text_line_cache_values (text_line);
switch (alignment) {
case ALIGN_CENTER:
return text_line->width / 2;
@@ -214,12 +216,18 @@ text_line_get_alignment_adjustment (TextLine *text_line, Alignment alignment)
case ALIGN_LEFT:
default:
return 0.0;
- }
+ }
}
/* **** Private functions **** */
-/** Mark this object as needing update before usage.
- * @param text_line the object that has changed.
+
+/**
+ * text_line_dirty_cache:
+ * @text_line: the object that has changed.
+ *
+ * Mark this object as needing update before usage.
+ *
+ * Since: dawn-of-time
*/
static void
text_line_dirty_cache(TextLine *text_line)
@@ -227,6 +235,7 @@ text_line_dirty_cache(TextLine *text_line)
text_line->clean = FALSE;
}
+
static void
clear_layout_offset (TextLine *text_line)
{
@@ -307,17 +316,21 @@ text_line_adjust_glyphs(TextLine *line, PangoGlyphString *glyphs, real scale)
}
}
-/** Adjust a layout line to match the more fine-grained values stored in the
- * textline. This circumvents the rounding errors in Pango and ensures a
+
+/**
+ * text_line_adjust_layout_line:
+ * @line: The #TextLine object that corresponds to the glyphs.
+ * @layoutline: The one set of glyphs contained in the #TextLine's layout.
+ * @scale: The relative height of the font in glyphs.
+ *
+ * Adjust a layout line to match the more fine-grained values stored in the
+ * textline. This circumvents the rounding errors in Pango and ensures a
* linear scaling for zooming and export filters.
- * @param line The TextLine object that corresponds to the glyphs.
- * @param layoutline The one set of glyphs contained in the TextLine's layout.
- * @param scale The relative height of the font in glyphs.
- * @return An adjusted glyphstring, which should be freed by the caller.
*/
void
-text_line_adjust_layout_line(TextLine *line, PangoLayoutLine *layoutline,
- real scale)
+text_line_adjust_layout_line (TextLine *line,
+ PangoLayoutLine *layoutline,
+ double scale)
{
GSList *layoutruns = layoutline->runs;
GSList *runs;
diff --git a/lib/textline.h b/lib/textline.h
index 7cc938d7..36edc7d1 100644
--- a/lib/textline.h
+++ b/lib/textline.h
@@ -32,32 +32,33 @@
*/
struct _TextLine {
/* don't change these values directly, use the text_line_set* functions */
-
+
/* Text data: */
- gchar *chars;
+ char *chars;
/* Attributes: */
DiaFont *font;
- real height;
-
+ double height;
+
/* Computed values, only access these through text_line_get* functions */
- real ascent;
- real descent;
- real width;
+ double ascent;
+ double descent;
+ double width;
+
+ /*< private >*/
- /* Private fields */
- /** Whether nothing has changed in this object since values were computed. */
+ /* Whether nothing has changed in this object since values were computed. */
gboolean clean;
- /** Copies of the real fields to keep track of changes caused by
+ /** Copies of the real fields to keep track of changes caused by
* properties setting. These may go away if we create TextLine properties.
*/
- gchar *chars_cache;
+ char *chars_cache;
DiaFont *font_cache;
- real height_cache;
+ double height_cache;
/** Offsets of the individual glyphs in the string. */
- real *offsets;
+ double *offsets;
PangoLayoutLine *layout_offsets;
};
@@ -80,7 +81,7 @@ void text_line_adjust_glyphs(TextLine *line,
real scale);
void text_line_adjust_layout_line(TextLine *line, PangoLayoutLine *layoutline,
real scale);
-real text_line_get_alignment_adjustment(TextLine *text_line,
+real text_line_get_alignment_adjustment(TextLine *text_line,
Alignment alignment);
#endif
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
