* generic/tcl.h (TCL_DEPRECATED_API): Added macro that can be used to

	mark parts of Tcl's API as deprecated. Currently only used for fields
	of Tcl_Interp, which TIPs 330 and 336 have deprecated with a migration
	strategy; we want to encourage people to move away from those fields.

2 files changed, 33 insertions, 6 deletions

diff --git a/ChangeLog b/ChangeLog
index c632c42..c735fae 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2012-04-10  Donal K. Fellows  <dkf@users.sf.net>
+
+	* generic/tcl.h (TCL_DEPRECATED_API): Added macro that can be used to
+	mark parts of Tcl's API as deprecated. Currently only used for fields
+	of Tcl_Interp, which TIPs 330 and 336 have deprecated with a migration
+	strategy; we want to encourage people to move away from those fields.
+
 2012-04-09  Donal K. Fellows  <dkf@users.sf.net>
 
 	* generic/tclOODefineCmds.c (ClassVarsSet, ObjVarsSet): [Bug 3396896]:
diff --git a/generic/tcl.h b/generic/tcl.h
index 875a171..729e521 100644
--- a/generic/tcl.h
+++ b/generic/tcl.h
@@ -163,6 +163,23 @@ extern "C" {
 #endif
 
 /*
+ * Allow a part of Tcl's API to be explicitly marked as deprecated.
+ *
+ * Used to make TIP 330/336 generate moans even if people use the
+ * compatibility macros. Change your code, guys! We won't support you forever.
+ */
+
+#if defined(__GNUC__) && ((__GNUC__ >= 4) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 1)))
+#   if (__GNUC__ > 4) || ((__GNUC__ == 4) && (__GNUC__MINOR__ >= 5))
+#	define TCL_DEPRECATED_API(msg)	__attribute__ ((__deprecated__ (msg)))
+#   else
+#	define TCL_DEPRECATED_API(msg)	__attribute__ ((__deprecated__))
+#   endif
+#else
+#   define TCL_DEPRECATED_API(msg)	/* nothing portable */
+#endif
+
+/*
  *----------------------------------------------------------------------------
  * Macros used to declare a function to be exported by a DLL. Used by Windows,
  * maps to no-op declarations on non-Windows systems. The default build on
@@ -487,9 +504,11 @@ typedef struct Tcl_Interp {
     /* TIP #330: Strongly discourage extensions from using the string
      * result. */
 #ifdef USE_INTERP_RESULT
-    char *result;		/* If the last command returned a string
+    char *result TCL_DEPRECATED_API("use Tcl_GetResult/Tcl_SetResult");
+				/* If the last command returned a string
 				 * result, this points to it. */
-    void (*freeProc) (char *blockPtr);
+    void (*freeProc) (char *blockPtr)
+	    TCL_DEPRECATED_API("use Tcl_GetResult/Tcl_SetResult");
 				/* Zero means the string result is statically
 				 * allocated. TCL_DYNAMIC means it was
 				 * allocated with ckalloc and should be freed
@@ -498,15 +517,16 @@ typedef struct Tcl_Interp {
 				 * Tcl_Eval must free it before executing next
 				 * command. */
 #else
-    char *unused3;
-    void (*unused4) (char *);
+    char *unused3 TCL_DEPRECATED_API("bad field access");
+    void (*unused4) (char *) TCL_DEPRECATED_API("bad field access");
 #endif
 #ifdef USE_INTERP_ERRORLINE
-    int errorLine;		/* When TCL_ERROR is returned, this gives the
+    int errorLine TCL_DEPRECATED_API("use Tcl_GetErrorLine/Tcl_SetErrorLine");
+				/* When TCL_ERROR is returned, this gives the
 				 * line number within the command where the
 				 * error occurred (1 if first line). */
 #else
-    int unused5;
+    int unused5 TCL_DEPRECATED_API("bad field access");
 #endif
 } Tcl_Interp;