I propose the attached patch to clean up the comment formatting in
plpgsql.h.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
>From 1924c0d822b36af32556e49cd0a70da9ab5c87b2 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut
Date: Tue, 16 Aug 2016 12:00:00 -0400
Subject: [PATCH] Improve formatting of comments in plpgsql.h
This file had some unusual comment layout. Most of the comments
introducing structs ended up to the right of the screen and following
the start of the struct. Some comments for struct members ended up
after the member definition.
Fix that by moving comments consistently before what they are
describing. Also add missing struct tags where missing so that it is
easier to tell what the struct is.
---
src/pl/plpgsql/src/plpgsql.h | 417 ++-
1 file changed, 255 insertions(+), 162 deletions(-)
diff --git a/src/pl/plpgsql/src/plpgsql.h b/src/pl/plpgsql/src/plpgsql.h
index 140bf4b..cd2e4ef 100644
--- a/src/pl/plpgsql/src/plpgsql.h
+++ b/src/pl/plpgsql/src/plpgsql.h
@@ -34,9 +34,8 @@
#undef _
#define _(x) dgettext(TEXTDOMAIN, x)
-/* --
+/*
* Compiler's namespace item types
- * --
*/
enum
{
@@ -46,9 +45,8 @@ enum
PLPGSQL_NSTYPE_REC
};
-/* --
+/*
* A PLPGSQL_NSTYPE_LABEL stack entry must be one of these types
- * --
*/
enum PLpgSQL_label_types
{
@@ -57,9 +55,8 @@ enum PLpgSQL_label_types
PLPGSQL_LABEL_OTHER /* anything else */
};
-/* --
+/*
* Datum array node types
- * --
*/
enum
{
@@ -71,9 +68,8 @@ enum
PLPGSQL_DTYPE_EXPR
};
-/* --
+/*
* Variants distinguished in PLpgSQL_type structs
- * --
*/
enum
{
@@ -83,9 +79,8 @@ enum
PLPGSQL_TTYPE_PSEUDO /* other pseudotypes */
};
-/* --
+/*
* Execution tree node types
- * --
*/
enum PLpgSQL_stmt_types
{
@@ -115,10 +110,8 @@ enum PLpgSQL_stmt_types
PLPGSQL_STMT_PERFORM
};
-
-/* --
+/*
* Execution node return codes
- * --
*/
enum
{
@@ -128,9 +121,8 @@ enum
PLPGSQL_RC_CONTINUE
};
-/* --
+/*
* GET DIAGNOSTICS information items
- * --
*/
enum
{
@@ -149,9 +141,8 @@ enum
PLPGSQL_GETDIAG_SCHEMA_NAME
};
-/*
+/*
* RAISE statement options
- *
*/
enum
{
@@ -166,9 +157,8 @@ enum
PLPGSQL_RAISEOPTION_SCHEMA
};
-/*
+/*
* Behavioral modes for plpgsql variable resolution
- *
*/
typedef enum
{
@@ -182,9 +172,11 @@ typedef enum
* Node and structure definitions
**/
-
-typedef struct
-{/* Postgres data type */
+/*
+ * Postgres data type
+ */
+typedef struct PLpgSQL_type
+{
char *typname; /* (simple) name of the type */
Oid typoid; /* OID of the data type */
int ttype; /* PLPGSQL_TTYPE_ code */
@@ -197,31 +189,37 @@ typedef struct
int32 atttypmod; /* typmod (taken from someplace else) */
} PLpgSQL_type;
-
/*
+ * Generic datum array item
+ *
* PLpgSQL_datum is the common supertype for PLpgSQL_expr, PLpgSQL_var,
* PLpgSQL_row, PLpgSQL_rec, PLpgSQL_recfield, and PLpgSQL_arrayelem
*/
-typedef struct
-{/* Generic datum array item */
+typedef struct PLpgSQL_datum
+{
int dtype;
int dno;
} PLpgSQL_datum;
/*
+ * Scalar or composite variable
+ *
* The variants PLpgSQL_var, PLpgSQL_row, and PLpgSQL_rec share these
* fields
*/
-typedef struct
-{/* Scalar or composite variable */
+typedef struct PLpgSQL_variable
+{
int dtype;
int dno;
char *refname;
int lineno;
} PLpgSQL_variable;
+/*
+ * SQL Query to plan and execute
+ */
typedef struct PLpgSQL_expr
-{/* SQL Query to plan and execute */
+{
int dtype;
int dno;
char *query;
@@ -252,9 +250,11 @@ typedef struct PLpgSQL_expr
LocalTransactionId expr_simple_lxid;
} PLpgSQL_expr;
-
-typedef struct
-{/* Scalar variable */
+/*
+ * Scalar variable
+ */
+typedef struct PLpgSQL_var
+{
int dtype;
int dno;
char *refname;
@@ -273,19 +273,20 @@ typedef struct
bool freeval;
} PLpgSQL_var;
-
-typedef struct
-{/* Row variable */
+/*
+ * Row variable
+ */
+typedef struct PLpgSQL_row
+{
int dtype;
int dno;
char *refname;
int lineno;
+ /* Note: TupleDesc is only set up for named rowtypes, else it is NULL. */
TupleDesc rowtupdesc;
/*
- * Note: TupleDesc is only set up for named rowtypes, else it is NULL.
- *
* Note: if the underlying rowtype contains a dropped column, the
* corresponding fieldnames[] entry will be NULL, and there is no
* corresponding var (varnos[] will be -1).
@@ -295,9 +296,11 @@ typedef struct
int *varnos;
} PLpgSQL_row;
-
-typedef struct
-{/* Record variable (non-fixed structure) */
+/*
+ * Record variable (non-fixed structure)
+ */
+typedef struct PLpgSQL_rec
+{
int dtype;
int dno;
char
