diff options
| author | Max Horn | 2010-10-31 21:50:20 +0000 |
|---|---|---|
| committer | Max Horn | 2010-10-31 21:50:20 +0000 |
| commit | e67ab53d89052f9100a1b4a9f0ace44c97beb20d (patch) | |
| tree | 87018c76d55fd106e5631e806ff8b4d2df146f3d | |
| parent | a41d4424af345c7ab89f8ffe06f96addf3ca751d (diff) | |
| download | scummvm-rg350-e67ab53d89052f9100a1b4a9f0ace44c97beb20d.tar.gz scummvm-rg350-e67ab53d89052f9100a1b4a9f0ace44c97beb20d.tar.bz2 scummvm-rg350-e67ab53d89052f9100a1b4a9f0ace44c97beb20d.zip | |
COMMON: Document forbidden.h
svn-id: r53990
| -rw-r--r-- | common/forbidden.h | 26 |
1 files changed, 20 insertions, 6 deletions
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! |