Commit 6d2db68f2ecd1f8b0945bc982af7a9807436d881
1 parent
da326893
Update comments in Constants.h
Showing
1 changed file
with
41 additions
and
1 deletions
include/qpdf/Constants.h
| @@ -23,10 +23,50 @@ | @@ -23,10 +23,50 @@ | ||
| 23 | #ifndef QPDFCONSTANTS_H | 23 | #ifndef QPDFCONSTANTS_H |
| 24 | #define QPDFCONSTANTS_H | 24 | #define QPDFCONSTANTS_H |
| 25 | 25 | ||
| 26 | -/* Keep this file 'C' compatible so it can be used from the C and C++ | 26 | +/* |
| 27 | + * REMEMBER: | ||
| 28 | + * | ||
| 29 | + * Keep this file 'C' compatible so it can be used from the C and C++ | ||
| 27 | * interfaces. | 30 | * interfaces. |
| 28 | */ | 31 | */ |
| 29 | 32 | ||
| 33 | +/* ****************************** NOTE ****************************** | ||
| 34 | + | ||
| 35 | +Tl;Dr: new values must be added to the end such that no constant's | ||
| 36 | +numerical value changes, even across major releases. | ||
| 37 | + | ||
| 38 | +Details: | ||
| 39 | + | ||
| 40 | +As new values are added to existing enumerated types in this file, | ||
| 41 | +it is important not to change the actual values of any constants. | ||
| 42 | +This means that, in the absence of explicit assignment of values, | ||
| 43 | +the order of entries can't change even across major releases. Why? | ||
| 44 | +Here are the reasons: | ||
| 45 | + | ||
| 46 | +* Many of these constants are used by the C API. The C API is used | ||
| 47 | + through foreign function call interfaces by users of other languages | ||
| 48 | + who may not have access to or the ability to parse a C header file. | ||
| 49 | + As such, users are likely to hard-code numerical values or create | ||
| 50 | + their own constants whose values match. If we change values here, | ||
| 51 | + their code would break, and there would be no way to detect it short | ||
| 52 | + of noticing a bug. Furthermore, it would be difficult to write code | ||
| 53 | + that properly handled more than one version of the qpdf shared | ||
| 54 | + object (e.g. DLL) since the information about what version of qpdf | ||
| 55 | + is involved is only available at runtime. | ||
| 56 | + | ||
| 57 | +- It has happened from time to time that a user builds an application | ||
| 58 | + with an incorrectly installed qpdf, such as having mismatched header | ||
| 59 | + files and library files. In the event that they are only using qpdf | ||
| 60 | + interfaces that have been stable across the versions in question, | ||
| 61 | + this turns out to be harmless. If they happen to use non-compatible | ||
| 62 | + interfaces, this results usually in a failure to load or an obvious | ||
| 63 | + runtime error. If we change values of constants, it is possible that | ||
| 64 | + code that links and runs may have mismatched values for constants. | ||
| 65 | + This would create a bug that would be extremely difficult to track | ||
| 66 | + down and impossible for qpdf maintainers to reproduce. | ||
| 67 | + | ||
| 68 | +*/ | ||
| 69 | + | ||
| 30 | /* Exit Codes from QPDFJob and the qpdf CLI */ | 70 | /* Exit Codes from QPDFJob and the qpdf CLI */ |
| 31 | 71 | ||
| 32 | enum qpdf_exit_code_e { | 72 | enum qpdf_exit_code_e { |