Fossil SCM
Have makeheaders ignore completely anonymous enums so they can be used within a single source file, useful for value autoincrementing. Update documentation accordingly. Write more about makeheaders's limitations discovered while researching this issue. Remove unnecessary explicit links to makeheaders.html in said file so it can be renamed without consequence. Ensure href attributes are surrounded by quotes. Add missing </html> to end of makeheaders.html.
Commit
4dcfbc1c8a82ed84ffaf632ee9e4c3976f36296d
Parent
26abbe3b04707bf…
2 files changed
+8
-3
+67
-31
+8
-3
| --- src/makeheaders.c | ||
| +++ src/makeheaders.c | ||
| @@ -1967,13 +1967,18 @@ | ||
| 1967 | 1967 | zFilename, pFirst->nLine); |
| 1968 | 1968 | nErr++; |
| 1969 | 1969 | } |
| 1970 | 1970 | pName = FindDeclName(pFirst,pEnd->pPrev); |
| 1971 | 1971 | if( pName==0 ){ |
| 1972 | - fprintf(stderr,"%s:%d: Can't find a name for the object declared here.\n", | |
| 1973 | - zFilename, pFirst->nLine); | |
| 1974 | - return nErr+1; | |
| 1972 | + if( pFirst->nText==4 && strncmp(pFirst->zText,"enum",4)==0 ){ | |
| 1973 | + /* Ignore completely anonymous enums. See documentation section 3.8.1. */ | |
| 1974 | + return nErr; | |
| 1975 | + }else{ | |
| 1976 | + fprintf(stderr,"%s:%d: Can't find a name for the object declared here.\n", | |
| 1977 | + zFilename, pFirst->nLine); | |
| 1978 | + return nErr+1; | |
| 1979 | + } | |
| 1975 | 1980 | } |
| 1976 | 1981 | |
| 1977 | 1982 | #ifdef DEBUG |
| 1978 | 1983 | if( debugMask & PARSER ){ |
| 1979 | 1984 | if( flags & PS_Typedef ){ |
| 1980 | 1985 |
| --- src/makeheaders.c | |
| +++ src/makeheaders.c | |
| @@ -1967,13 +1967,18 @@ | |
| 1967 | zFilename, pFirst->nLine); |
| 1968 | nErr++; |
| 1969 | } |
| 1970 | pName = FindDeclName(pFirst,pEnd->pPrev); |
| 1971 | if( pName==0 ){ |
| 1972 | fprintf(stderr,"%s:%d: Can't find a name for the object declared here.\n", |
| 1973 | zFilename, pFirst->nLine); |
| 1974 | return nErr+1; |
| 1975 | } |
| 1976 | |
| 1977 | #ifdef DEBUG |
| 1978 | if( debugMask & PARSER ){ |
| 1979 | if( flags & PS_Typedef ){ |
| 1980 |
| --- src/makeheaders.c | |
| +++ src/makeheaders.c | |
| @@ -1967,13 +1967,18 @@ | |
| 1967 | zFilename, pFirst->nLine); |
| 1968 | nErr++; |
| 1969 | } |
| 1970 | pName = FindDeclName(pFirst,pEnd->pPrev); |
| 1971 | if( pName==0 ){ |
| 1972 | if( pFirst->nText==4 && strncmp(pFirst->zText,"enum",4)==0 ){ |
| 1973 | /* Ignore completely anonymous enums. See documentation section 3.8.1. */ |
| 1974 | return nErr; |
| 1975 | }else{ |
| 1976 | fprintf(stderr,"%s:%d: Can't find a name for the object declared here.\n", |
| 1977 | zFilename, pFirst->nLine); |
| 1978 | return nErr+1; |
| 1979 | } |
| 1980 | } |
| 1981 | |
| 1982 | #ifdef DEBUG |
| 1983 | if( debugMask & PARSER ){ |
| 1984 | if( flags & PS_Typedef ){ |
| 1985 |
+67
-31
| --- src/makeheaders.html | ||
| +++ src/makeheaders.html | ||
| @@ -12,41 +12,41 @@ | ||
| 12 | 12 | |
| 13 | 13 | |
| 14 | 14 | <h2>Table Of Contents</h2> |
| 15 | 15 | |
| 16 | 16 | <ul> |
| 17 | -<li><a href=makeheaders.html#H0002>1,0 Background</a> | |
| 18 | -<ul> | |
| 19 | -<li><a href=makeheaders.html#H0003>1.1 Problems With The Traditional Approach</a> | |
| 20 | - | |
| 21 | -<li><a href=makeheaders.html#H0004>1.2 The Makeheaders Solution</a> | |
| 22 | -</ul> | |
| 23 | -<li><a href=makeheaders.html#H0005>2.0 Running The Makeheaders Program</a> | |
| 24 | - | |
| 25 | -<li><a href=makeheaders.html#H0006>3.0 Preparing Source Files For Use With Makeheaders</a> | |
| 26 | -<ul> | |
| 27 | -<li><a href=makeheaders.html#H0007>3.1 The Basic Setup</a> | |
| 28 | - | |
| 29 | -<li><a href=makeheaders.html#H0008>3.2 What Declarations Get Copied</a> | |
| 30 | - | |
| 31 | -<li><a href=makeheaders.html#H0009>3.3 How To Avoid Having To Write Any Header Files</a> | |
| 32 | - | |
| 33 | -<li><a href=makeheaders.html#H0010>3.4 Designating Declarations For Export</a> | |
| 34 | - | |
| 35 | -<li><a href=makeheaders.html#H0011>3.5 Local declarations processed by makeheaders</a> | |
| 36 | - | |
| 37 | -<li><a href=makeheaders.html#H0012>3.6 Using Makeheaders With C++ Code</a> | |
| 38 | - | |
| 39 | -<li><a href=makeheaders.html#H0013>3.7 Conditional Compilation</a> | |
| 40 | - | |
| 41 | -<li><a href=makeheaders.html#H0014>3.8 Caveats</a> | |
| 42 | -</ul> | |
| 43 | -<li><a href=makeheaders.html#H0015>4.0 Using Makeheaders To Generate Documentation</a> | |
| 44 | - | |
| 45 | -<li><a href=makeheaders.html#H0016>5.0 Compiling The Makeheaders Program</a> | |
| 46 | - | |
| 47 | -<li><a href=makeheaders.html#H0017>6.0 Summary And Conclusion</a> | |
| 17 | +<li><a href="#H0002">1,0 Background</a> | |
| 18 | +<ul> | |
| 19 | +<li><a href="#H0003">1.1 Problems With The Traditional Approach</a> | |
| 20 | + | |
| 21 | +<li><a href="#H0004">1.2 The Makeheaders Solution</a> | |
| 22 | +</ul> | |
| 23 | +<li><a href="#H0005">2.0 Running The Makeheaders Program</a> | |
| 24 | + | |
| 25 | +<li><a href="#H0006">3.0 Preparing Source Files For Use With Makeheaders</a> | |
| 26 | +<ul> | |
| 27 | +<li><a href="#H0007">3.1 The Basic Setup</a> | |
| 28 | + | |
| 29 | +<li><a href="#H0008">3.2 What Declarations Get Copied</a> | |
| 30 | + | |
| 31 | +<li><a href="#H0009">3.3 How To Avoid Having To Write Any Header Files</a> | |
| 32 | + | |
| 33 | +<li><a href="#H0010">3.4 Designating Declarations For Export</a> | |
| 34 | + | |
| 35 | +<li><a href="#H0011">3.5 Local declarations processed by makeheaders</a> | |
| 36 | + | |
| 37 | +<li><a href="#H0012">3.6 Using Makeheaders With C++ Code</a> | |
| 38 | + | |
| 39 | +<li><a href="#H0013">3.7 Conditional Compilation</a> | |
| 40 | + | |
| 41 | +<li><a href="#H0014">3.8 Caveats</a> | |
| 42 | +</ul> | |
| 43 | +<li><a href="#H0015">4.0 Using Makeheaders To Generate Documentation</a> | |
| 44 | + | |
| 45 | +<li><a href="#H0016">5.0 Compiling The Makeheaders Program</a> | |
| 46 | + | |
| 47 | +<li><a href="#H0017">6.0 Summary And Conclusion</a> | |
| 48 | 48 | </ul><a name="H0002"></a> |
| 49 | 49 | <h2>1.0 Background</h2> |
| 50 | 50 | |
| 51 | 51 | <p> |
| 52 | 52 | A piece of C source code can be one of two things: |
| @@ -929,10 +929,30 @@ | ||
| 929 | 929 | become very confused if it encounters an old K&R function. |
| 930 | 930 | Therefore you should take care to avoid putting K&R function definitions |
| 931 | 931 | in your code. |
| 932 | 932 | </p> |
| 933 | 933 | |
| 934 | +<p> | |
| 935 | +Makeheaders does not support defining an enumerated or aggregate type in | |
| 936 | +the same statement as a variable declaration. None of the following | |
| 937 | +statements work completely: | |
| 938 | +<pre> | |
| 939 | +struct {int field;} a; | |
| 940 | +struct Tag {int field;} b; | |
| 941 | +struct Tag c; | |
| 942 | +</pre> | |
| 943 | +Instead, define types separately from variables: | |
| 944 | +<pre> | |
| 945 | +#if INTERFACE | |
| 946 | +struct Tag {int field;}; | |
| 947 | +#endif | |
| 948 | +Tag b, c; | |
| 949 | +</pre> | |
| 950 | +See <a href="#H0008">3.2 What Declarations Get Copied</a> for details, | |
| 951 | +including on the automatic typedef. | |
| 952 | +</p> | |
| 953 | + | |
| 934 | 954 | <p> |
| 935 | 955 | Makeheaders does not understand when you define more than one |
| 936 | 956 | global variable with the same type separated by a comma. |
| 937 | 957 | In other words, makeheaders does not understand this: |
| 938 | 958 | <pre> |
| @@ -980,10 +1000,25 @@ | ||
| 980 | 1000 | As long as you avoid excessive cleverness, makeheaders will |
| 981 | 1001 | probably be able to figure out what you want and will do the right |
| 982 | 1002 | thing. |
| 983 | 1003 | </p> |
| 984 | 1004 | |
| 1005 | +<p> | |
| 1006 | +Makeheaders has limited understanding of enums. In particular, it does | |
| 1007 | +not realize the significance of enumerated values, so the enum is not | |
| 1008 | +emitted in the header files when its enumerated values are used unless | |
| 1009 | +the name associated with the enum is also used. Moreover, enums can be | |
| 1010 | +completely anonymous, e.g. “<code>enum {X, Y, Z};</code>”. | |
| 1011 | +Makeheaders ignores such enums so they can at least be used within a | |
| 1012 | +single source file. Makeheaders expects you to use #define constants | |
| 1013 | +instead. If you want enum features that #define lacks, and you need the | |
| 1014 | +enum in the interface, bypass makeheaders and write a header file by | |
| 1015 | +hand, or teach makeheaders to emit the enum definition when any of the | |
| 1016 | +enumerated values are used, rather than only when the top-level name (if | |
| 1017 | +any) is used. | |
| 1018 | +</p> | |
| 1019 | + | |
| 985 | 1020 | <a name="H0015"></a> |
| 986 | 1021 | <h2>4.0 Using Makeheaders To Generate Documentation</h2> |
| 987 | 1022 | |
| 988 | 1023 | <p> |
| 989 | 1024 | Many people have observed the advantages of generating program |
| @@ -1081,5 +1116,6 @@ | ||
| 1081 | 1116 | In at least two cases, makeheaders has facilitated development |
| 1082 | 1117 | of programs that would have otherwise been all but impossible |
| 1083 | 1118 | due to their size and complexity. |
| 1084 | 1119 | </p> |
| 1085 | 1120 | </body> |
| 1121 | +</html> | |
| 1086 | 1122 |
| --- src/makeheaders.html | |
| +++ src/makeheaders.html | |
| @@ -12,41 +12,41 @@ | |
| 12 | |
| 13 | |
| 14 | <h2>Table Of Contents</h2> |
| 15 | |
| 16 | <ul> |
| 17 | <li><a href=makeheaders.html#H0002>1,0 Background</a> |
| 18 | <ul> |
| 19 | <li><a href=makeheaders.html#H0003>1.1 Problems With The Traditional Approach</a> |
| 20 | |
| 21 | <li><a href=makeheaders.html#H0004>1.2 The Makeheaders Solution</a> |
| 22 | </ul> |
| 23 | <li><a href=makeheaders.html#H0005>2.0 Running The Makeheaders Program</a> |
| 24 | |
| 25 | <li><a href=makeheaders.html#H0006>3.0 Preparing Source Files For Use With Makeheaders</a> |
| 26 | <ul> |
| 27 | <li><a href=makeheaders.html#H0007>3.1 The Basic Setup</a> |
| 28 | |
| 29 | <li><a href=makeheaders.html#H0008>3.2 What Declarations Get Copied</a> |
| 30 | |
| 31 | <li><a href=makeheaders.html#H0009>3.3 How To Avoid Having To Write Any Header Files</a> |
| 32 | |
| 33 | <li><a href=makeheaders.html#H0010>3.4 Designating Declarations For Export</a> |
| 34 | |
| 35 | <li><a href=makeheaders.html#H0011>3.5 Local declarations processed by makeheaders</a> |
| 36 | |
| 37 | <li><a href=makeheaders.html#H0012>3.6 Using Makeheaders With C++ Code</a> |
| 38 | |
| 39 | <li><a href=makeheaders.html#H0013>3.7 Conditional Compilation</a> |
| 40 | |
| 41 | <li><a href=makeheaders.html#H0014>3.8 Caveats</a> |
| 42 | </ul> |
| 43 | <li><a href=makeheaders.html#H0015>4.0 Using Makeheaders To Generate Documentation</a> |
| 44 | |
| 45 | <li><a href=makeheaders.html#H0016>5.0 Compiling The Makeheaders Program</a> |
| 46 | |
| 47 | <li><a href=makeheaders.html#H0017>6.0 Summary And Conclusion</a> |
| 48 | </ul><a name="H0002"></a> |
| 49 | <h2>1.0 Background</h2> |
| 50 | |
| 51 | <p> |
| 52 | A piece of C source code can be one of two things: |
| @@ -929,10 +929,30 @@ | |
| 929 | become very confused if it encounters an old K&R function. |
| 930 | Therefore you should take care to avoid putting K&R function definitions |
| 931 | in your code. |
| 932 | </p> |
| 933 | |
| 934 | <p> |
| 935 | Makeheaders does not understand when you define more than one |
| 936 | global variable with the same type separated by a comma. |
| 937 | In other words, makeheaders does not understand this: |
| 938 | <pre> |
| @@ -980,10 +1000,25 @@ | |
| 980 | As long as you avoid excessive cleverness, makeheaders will |
| 981 | probably be able to figure out what you want and will do the right |
| 982 | thing. |
| 983 | </p> |
| 984 | |
| 985 | <a name="H0015"></a> |
| 986 | <h2>4.0 Using Makeheaders To Generate Documentation</h2> |
| 987 | |
| 988 | <p> |
| 989 | Many people have observed the advantages of generating program |
| @@ -1081,5 +1116,6 @@ | |
| 1081 | In at least two cases, makeheaders has facilitated development |
| 1082 | of programs that would have otherwise been all but impossible |
| 1083 | due to their size and complexity. |
| 1084 | </p> |
| 1085 | </body> |
| 1086 |
| --- src/makeheaders.html | |
| +++ src/makeheaders.html | |
| @@ -12,41 +12,41 @@ | |
| 12 | |
| 13 | |
| 14 | <h2>Table Of Contents</h2> |
| 15 | |
| 16 | <ul> |
| 17 | <li><a href="#H0002">1,0 Background</a> |
| 18 | <ul> |
| 19 | <li><a href="#H0003">1.1 Problems With The Traditional Approach</a> |
| 20 | |
| 21 | <li><a href="#H0004">1.2 The Makeheaders Solution</a> |
| 22 | </ul> |
| 23 | <li><a href="#H0005">2.0 Running The Makeheaders Program</a> |
| 24 | |
| 25 | <li><a href="#H0006">3.0 Preparing Source Files For Use With Makeheaders</a> |
| 26 | <ul> |
| 27 | <li><a href="#H0007">3.1 The Basic Setup</a> |
| 28 | |
| 29 | <li><a href="#H0008">3.2 What Declarations Get Copied</a> |
| 30 | |
| 31 | <li><a href="#H0009">3.3 How To Avoid Having To Write Any Header Files</a> |
| 32 | |
| 33 | <li><a href="#H0010">3.4 Designating Declarations For Export</a> |
| 34 | |
| 35 | <li><a href="#H0011">3.5 Local declarations processed by makeheaders</a> |
| 36 | |
| 37 | <li><a href="#H0012">3.6 Using Makeheaders With C++ Code</a> |
| 38 | |
| 39 | <li><a href="#H0013">3.7 Conditional Compilation</a> |
| 40 | |
| 41 | <li><a href="#H0014">3.8 Caveats</a> |
| 42 | </ul> |
| 43 | <li><a href="#H0015">4.0 Using Makeheaders To Generate Documentation</a> |
| 44 | |
| 45 | <li><a href="#H0016">5.0 Compiling The Makeheaders Program</a> |
| 46 | |
| 47 | <li><a href="#H0017">6.0 Summary And Conclusion</a> |
| 48 | </ul><a name="H0002"></a> |
| 49 | <h2>1.0 Background</h2> |
| 50 | |
| 51 | <p> |
| 52 | A piece of C source code can be one of two things: |
| @@ -929,10 +929,30 @@ | |
| 929 | become very confused if it encounters an old K&R function. |
| 930 | Therefore you should take care to avoid putting K&R function definitions |
| 931 | in your code. |
| 932 | </p> |
| 933 | |
| 934 | <p> |
| 935 | Makeheaders does not support defining an enumerated or aggregate type in |
| 936 | the same statement as a variable declaration. None of the following |
| 937 | statements work completely: |
| 938 | <pre> |
| 939 | struct {int field;} a; |
| 940 | struct Tag {int field;} b; |
| 941 | struct Tag c; |
| 942 | </pre> |
| 943 | Instead, define types separately from variables: |
| 944 | <pre> |
| 945 | #if INTERFACE |
| 946 | struct Tag {int field;}; |
| 947 | #endif |
| 948 | Tag b, c; |
| 949 | </pre> |
| 950 | See <a href="#H0008">3.2 What Declarations Get Copied</a> for details, |
| 951 | including on the automatic typedef. |
| 952 | </p> |
| 953 | |
| 954 | <p> |
| 955 | Makeheaders does not understand when you define more than one |
| 956 | global variable with the same type separated by a comma. |
| 957 | In other words, makeheaders does not understand this: |
| 958 | <pre> |
| @@ -980,10 +1000,25 @@ | |
| 1000 | As long as you avoid excessive cleverness, makeheaders will |
| 1001 | probably be able to figure out what you want and will do the right |
| 1002 | thing. |
| 1003 | </p> |
| 1004 | |
| 1005 | <p> |
| 1006 | Makeheaders has limited understanding of enums. In particular, it does |
| 1007 | not realize the significance of enumerated values, so the enum is not |
| 1008 | emitted in the header files when its enumerated values are used unless |
| 1009 | the name associated with the enum is also used. Moreover, enums can be |
| 1010 | completely anonymous, e.g. “<code>enum {X, Y, Z};</code>”. |
| 1011 | Makeheaders ignores such enums so they can at least be used within a |
| 1012 | single source file. Makeheaders expects you to use #define constants |
| 1013 | instead. If you want enum features that #define lacks, and you need the |
| 1014 | enum in the interface, bypass makeheaders and write a header file by |
| 1015 | hand, or teach makeheaders to emit the enum definition when any of the |
| 1016 | enumerated values are used, rather than only when the top-level name (if |
| 1017 | any) is used. |
| 1018 | </p> |
| 1019 | |
| 1020 | <a name="H0015"></a> |
| 1021 | <h2>4.0 Using Makeheaders To Generate Documentation</h2> |
| 1022 | |
| 1023 | <p> |
| 1024 | Many people have observed the advantages of generating program |
| @@ -1081,5 +1116,6 @@ | |
| 1116 | In at least two cases, makeheaders has facilitated development |
| 1117 | of programs that would have otherwise been all but impossible |
| 1118 | due to their size and complexity. |
| 1119 | </p> |
| 1120 | </body> |
| 1121 | </html> |
| 1122 |