Fossil

Check-in [4dcfbc1c]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment: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.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:4dcfbc1c8a82ed84ffaf632ee9e4c3976f36296d
User & Date: andygoth 2016-11-05 19:24:26
Context
2016-11-05
19:51
Add the "History" section to the makeheaders documentation. check-in: 28098136 user: drh tags: trunk
19:25
Merge trunk check-in: e6787d1e user: andygoth tags: andygoth-changes
19:24
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. check-in: 4dcfbc1c user: andygoth tags: trunk
16:08
Add missing title tags to documents check-in: 26abbe3b user: andygoth tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/makeheaders.c.

1965
1966
1967
1968
1969
1970
1971




1972
1973
1974

1975
1976
1977
1978
1979
1980
1981
  && (flags & PS_Extern)==0 ){
    fprintf(stderr,"%s:%d: Can't define a variable in this context\n",
      zFilename, pFirst->nLine);
    nErr++;
  }
  pName = FindDeclName(pFirst,pEnd->pPrev);
  if( pName==0 ){




    fprintf(stderr,"%s:%d: Can't find a name for the object declared here.\n",
      zFilename, pFirst->nLine);
    return nErr+1;

  }

#ifdef DEBUG
  if( debugMask & PARSER ){
    if( flags & PS_Typedef ){
      printf("**** Found typedef %.*s at line %d...\n",
        pName->nText, pName->zText, pName->nLine);







>
>
>
>
|
|
|
>







1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
  && (flags & PS_Extern)==0 ){
    fprintf(stderr,"%s:%d: Can't define a variable in this context\n",
      zFilename, pFirst->nLine);
    nErr++;
  }
  pName = FindDeclName(pFirst,pEnd->pPrev);
  if( pName==0 ){
    if( pFirst->nText==4 && strncmp(pFirst->zText,"enum",4)==0 ){
      /* Ignore completely anonymous enums.  See documentation section 3.8.1. */
      return nErr;
    }else{
      fprintf(stderr,"%s:%d: Can't find a name for the object declared here.\n",
        zFilename, pFirst->nLine);
      return nErr+1;
    }
  }

#ifdef DEBUG
  if( debugMask & PARSER ){
    if( flags & PS_Typedef ){
      printf("**** Found typedef %.*s at line %d...\n",
        pName->nText, pName->zText, pName->nLine);

Changes to src/makeheaders.html.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
...
927
928
929
930
931
932
933




















934
935
936
937
938
939
940
...
978
979
980
981
982
983
984















985
986
987
988
989
990
991
....
1079
1080
1081
1082
1083
1084
1085

files for a C or C++ programming project.
</p>


<h2>Table Of Contents</h2>

<ul>
<li><a href=makeheaders.html#H0002>1,0 Background</a>
<ul>
<li><a href=makeheaders.html#H0003>1.1 Problems With The Traditional Approach</a>

<li><a href=makeheaders.html#H0004>1.2 The Makeheaders Solution</a>
</ul>
<li><a href=makeheaders.html#H0005>2.0 Running The Makeheaders Program</a>

<li><a href=makeheaders.html#H0006>3.0 Preparing Source Files For Use With Makeheaders</a>
<ul>
<li><a href=makeheaders.html#H0007>3.1 The Basic Setup</a>

<li><a href=makeheaders.html#H0008>3.2 What Declarations Get Copied</a>

<li><a href=makeheaders.html#H0009>3.3 How To Avoid Having To Write Any Header Files</a>

<li><a href=makeheaders.html#H0010>3.4 Designating Declarations For Export</a>

<li><a href=makeheaders.html#H0011>3.5 Local declarations processed by makeheaders</a>

<li><a href=makeheaders.html#H0012>3.6 Using Makeheaders With C++ Code</a>

<li><a href=makeheaders.html#H0013>3.7 Conditional Compilation</a>

<li><a href=makeheaders.html#H0014>3.8 Caveats</a>
</ul>
<li><a href=makeheaders.html#H0015>4.0 Using Makeheaders To Generate Documentation</a>

<li><a href=makeheaders.html#H0016>5.0 Compiling The Makeheaders Program</a>

<li><a href=makeheaders.html#H0017>6.0 Summary And Conclusion</a>
</ul><a name="H0002"></a>
<h2>1.0 Background</h2>

<p>
A piece of C source code can be one of two things:
a <em>declaration</em> or a <em>definition</em>.
A declaration is source text that gives information to the
................................................................................
and procedure definitions.
It only understands the modern ANSI-C style, and will probably
become very confused if it encounters an old K&amp;R function.
Therefore you should take care to avoid putting K&amp;R function definitions
in your code.
</p>





















<p>
Makeheaders does not understand when you define more than one
global variable with the same type separated by a comma.
In other words, makeheaders does not understand this:
<pre>
   int a = 4, b = 5;
</pre>
................................................................................
For most projects the code constructs that makeheaders cannot
handle are very rare.
As long as you avoid excessive cleverness, makeheaders will
probably be able to figure out what you want and will do the right
thing.
</p>
















<a name="H0015"></a>
<h2>4.0 Using Makeheaders To Generate Documentation</h2>

<p>
Many people have observed the advantages of generating program
documentation directly from the source code:
<ul>
................................................................................
to be a very helpful aid
in the construction and maintenance of large C codes.
In at least two cases, makeheaders has facilitated development
of programs that would have otherwise been all but impossible
due to their size and complexity.
</p>
</body>








|

|

|

|

|

|

|

|

|

|

|

|

|

|

|

|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
...
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
...
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
....
1114
1115
1116
1117
1118
1119
1120
1121
files for a C or C++ programming project.
</p>


<h2>Table Of Contents</h2>

<ul>
<li><a href="#H0002">1,0 Background</a>
<ul>
<li><a href="#H0003">1.1 Problems With The Traditional Approach</a>

<li><a href="#H0004">1.2 The Makeheaders Solution</a>
</ul>
<li><a href="#H0005">2.0 Running The Makeheaders Program</a>

<li><a href="#H0006">3.0 Preparing Source Files For Use With Makeheaders</a>
<ul>
<li><a href="#H0007">3.1 The Basic Setup</a>

<li><a href="#H0008">3.2 What Declarations Get Copied</a>

<li><a href="#H0009">3.3 How To Avoid Having To Write Any Header Files</a>

<li><a href="#H0010">3.4 Designating Declarations For Export</a>

<li><a href="#H0011">3.5 Local declarations processed by makeheaders</a>

<li><a href="#H0012">3.6 Using Makeheaders With C++ Code</a>

<li><a href="#H0013">3.7 Conditional Compilation</a>

<li><a href="#H0014">3.8 Caveats</a>
</ul>
<li><a href="#H0015">4.0 Using Makeheaders To Generate Documentation</a>

<li><a href="#H0016">5.0 Compiling The Makeheaders Program</a>

<li><a href="#H0017">6.0 Summary And Conclusion</a>
</ul><a name="H0002"></a>
<h2>1.0 Background</h2>

<p>
A piece of C source code can be one of two things:
a <em>declaration</em> or a <em>definition</em>.
A declaration is source text that gives information to the
................................................................................
and procedure definitions.
It only understands the modern ANSI-C style, and will probably
become very confused if it encounters an old K&amp;R function.
Therefore you should take care to avoid putting K&amp;R function definitions
in your code.
</p>

<p>
Makeheaders does not support defining an enumerated or aggregate type in
the same statement as a variable declaration.  None of the following
statements work completely:
<pre>
struct {int field;} a;
struct Tag {int field;} b;
struct Tag c;
</pre>
Instead, define types separately from variables:
<pre>
#if INTERFACE
struct Tag {int field;};
#endif
Tag b, c;
</pre>
See <a href="#H0008">3.2 What Declarations Get Copied</a> for details,
including on the automatic typedef.
</p>

<p>
Makeheaders does not understand when you define more than one
global variable with the same type separated by a comma.
In other words, makeheaders does not understand this:
<pre>
   int a = 4, b = 5;
</pre>
................................................................................
For most projects the code constructs that makeheaders cannot
handle are very rare.
As long as you avoid excessive cleverness, makeheaders will
probably be able to figure out what you want and will do the right
thing.
</p>

<p>
Makeheaders has limited understanding of enums.  In particular, it does
not realize the significance of enumerated values, so the enum is not
emitted in the header files when its enumerated values are used unless
the name associated with the enum is also used.  Moreover, enums can be
completely anonymous, e.g. &#8220;<code>enum {X, Y, Z};</code>&#8221;.
Makeheaders ignores such enums so they can at least be used within a
single source file.  Makeheaders expects you to use #define constants
instead.  If you want enum features that #define lacks, and you need the
enum in the interface, bypass makeheaders and write a header file by
hand, or teach makeheaders to emit the enum definition when any of the
enumerated values are used, rather than only when the top-level name (if
any) is used.
</p>

<a name="H0015"></a>
<h2>4.0 Using Makeheaders To Generate Documentation</h2>

<p>
Many people have observed the advantages of generating program
documentation directly from the source code:
<ul>
................................................................................
to be a very helpful aid
in the construction and maintenance of large C codes.
In at least two cases, makeheaders has facilitated development
of programs that would have otherwise been all but impossible
due to their size and complexity.
</p>
</body>
</html>