From e67ab53d89052f9100a1b4a9f0ace44c97beb20d Mon Sep 17 00:00:00 2001
From: Max Horn
Date: Sun, 31 Oct 2010 21:50:20 +0000
Subject: COMMON: Document forbidden.h

svn-id: r53990
---
 common/forbidden.h | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

(limited to 'common')

diff --git a/common/forbidden.h b/common/forbidden.h
index cc71c36711..92e662ccc6 100644
--- a/common/forbidden.h
+++ b/common/forbidden.h
@@ -26,15 +26,29 @@
 #ifndef COMMON_FORBIDDEN_H
 #define COMMON_FORBIDDEN_H
 
-
-//
-// Backend files may #define FORBIDDEN_SYMBOL_ALLOW_ALL if they
-// have to access functions like fopen, fread etc.
-// Regular code, esp. code in engines/, should never do that.
-//
+/**
+ * @file
+ * This header file is meant to help ensure that engines and
+ * infrastructure code do not make use of certain "forbidden" APIs, such
+ * as fopen(), setjmp(), etc.
+ * This is achieved by re-#defining various symbols to a "garbage"
+ * string which then trigers a compiler error.
+ *
+ * Backend files may #define FORBIDDEN_SYMBOL_ALLOW_ALL if they
+ * have to access functions like fopen, fread etc.
+ * Regular code, esp. code in engines/, should never do that.
+ */
 
 #ifndef FORBIDDEN_SYMBOL_ALLOW_ALL
 
+/**
+ * The garbage string to use as replacement for forbidden symbols.
+ *
+ * The reason for this particular string is the following:
+ * By including a space and "!" we try to ensure a compiler error.
+ * By using the words "forbidden symbol" we try to make it a bit
+ * clearer what is causing the error.
+ */
 #define FORBIDDEN_SYMBOL_REPLACEMENT	FORBIDDEN SYMBOL!
 
 
-- 
cgit v1.2.3