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 | 23 | #ifndef QPDFCONSTANTS_H |
| 24 | 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 | 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 | 70 | /* Exit Codes from QPDFJob and the qpdf CLI */ |
| 31 | 71 | |
| 32 | 72 | enum qpdf_exit_code_e { | ... | ... |