← Back to branch summary

~ubuntu-branches/ubuntu/saucy/gtk-doc/saucy

« back to all changes in this revision

Viewing changes to gtkdoc-mktmpl.in

  • Committer: Bazaar Package Importer
  • Author(s): Sebastian Dröge
  • Date: 2009-02-17 17:11:41 UTC
  • mto: (1.2.8 upstream) (4.1.2 squeeze)
  • mto: This revision was merged to the branch mainline in revision 11.
  • Revision ID: james.westby@ubuntu.com-20090217171141-nobu8ey8kqtq5alx
Import upstream version 1.11

Show diffs side-by-side

added added

removed removed

Lines of Context:
gtkdoc-mktmpl.in
38
38
#
39
39
#               Any templates which are no longer used (i.e. they are remove
40
40
#               from $MODULE-sections.txt) are placed in the file
41
 
#               tmpl/$MODULE-unused.txt. If they are included again later
 
41
#               tmpl/$MODULE-unused.sgml. If they are included again later
42
42
#               they are automatically copied back into position.
43
43
#               If you are certain that these templates will never be used
44
 
#               again you can delete them from $MODULE-unused.txt.
 
44
#               again you can delete them from tmpl/$MODULE-unused.sgml.
45
45
#
46
46
#               Any parameters to functions which are no longer used are
47
47
#               separated from the rest of the parameters with the line
67
67
my $PRINT_HELP;
68
68
my $ONLY_SECTION_TMPL;
69
69
 
70
 
my %optctl = (module => \$MODULE,
 
70
my %optctl = ('module' => \$MODULE,
71
71
              'flag-changes' => \$FLAG_CHANGES,
72
72
              'output-dir' => \$TMPL_DIR,
73
73
              'only-section-tmpl' => \$ONLY_SECTION_TMPL,
85
85
}
86
86
 
87
87
if ($PRINT_HELP) {
88
 
    print "gtkdoc-mktmpl version @VERSION@\n";
89
 
    print "\n--module=MODULE_NAME Name of the doc module being parsed";
90
 
    print "\n--flag-changes       If specified, changes in templates are flagged";
91
 
    print "\n--output-dir=DIRNAME The directory where the results are stored";
92
 
    print "\n--only-section-tmpl  Only include section information in templates";
93
 
    print "\n--version            Print the version of this program";
94
 
    print "\n--help               Print this help\n";
 
88
    print <<EOF;
 
89
gtkdoc-mktmpl version @VERSION@
 
90
 
 
91
--module=MODULE_NAME Name of the doc module being parsed
 
92
--flag-changes       If specified, changes in templates are flagged
 
93
--output-dir=DIRNAME The directory where the results are stored
 
94
--only-section-tmpl  Only include section information in templates
 
95
--version            Print the version of this program
 
96
--help               Print this help
 
97
EOF
95
98
    exit 0;
96
99
}
97
100
 
137
140
my %SymbolDocs;
138
141
my %SymbolTypes;
139
142
my %SymbolParams;
 
143
my %SymbolSourceFile;
 
144
my %SymbolSourceLine;
140
145
 
141
 
# These global arrays store GtkObject and subclasses and the hierarchy.
 
146
# These global arrays store GObject and subclasses and the hierarchy.
142
147
my @Objects;
143
148
my @ObjectLevels;
144
149
 
220
225
            || die "Can't create directory: $TMPL_DIR";
221
226
    }
222
227
 
 
228
    my $filename = "";
223
229
    my $title = "";
224
230
    my $subsection = "";
225
231
    my $output;
240
246
#           print "Section: $title\n";
241
247
 
242
248
        } elsif (m/^<FILE>(.*)<\/FILE>/) {
243
 
            $file = $1;
 
249
            $filename = $1;
244
250
 
245
251
        } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
246
252
            next;
247
253
 
248
254
        } elsif (m/^<\/SECTION>/) {
249
255
            if ($title eq "") {
250
 
                $title = $file;
 
256
                $title = $filename;
251
257
            }
252
258
#           print "End of section: $title\n";
253
259
 
254
 
            $file =~ s/\s/_/g;
255
 
            $file .= ".sgml";
 
260
            $filename =~ s/\s/_/g;
 
261
            $filename .= ".sgml";
256
262
 
257
 
            if (&OutputTemplateFile ($file, $title, \$output)) {
 
263
            if (&OutputTemplateFile ($filename, $title, \$output)) {
258
264
              $changed = 1;
259
265
            }
260
266
 
268
274
            my $declaration = $Declarations{$1};
269
275
            if (defined ($declaration)) {
270
276
                # We don't want templates for standard macros/functions of
271
 
                # GtkObjects or private declarations.
 
277
                # GObjects or private declarations.
272
278
                if ($subsection ne "Standard" && $subsection ne "Private") {
273
279
                    $output .= &OutputDeclaration ($DeclarationTypes {$symbol},
274
280
                                                   $symbol, $declaration);
285
291
                }
286
292
 
287
293
            } else {
288
 
                print "WARNING: No declaration found for: $1\n";
 
294
                &LogWarning ($file, $., "No declaration found for: $1");
289
295
            }
290
296
        }
291
297
    }
301
307
#               makes sure that each one has been output, by checking the
302
308
#               corresponding flag in the %DeclarationOutput hash. It is
303
309
#               intended to check that any new declarations in new versions
304
 
#               of GTK/Gnome get added to the $MODULE-sections.txt file.
 
310
#               of the module get added to the $MODULE-sections.txt file.
305
311
# Arguments   : none
306
312
#############################################################################
307
313
 
322
328
    }
323
329
    close (UNUSED);
324
330
    if ($num_unused != 0) {
325
 
        print <<EOF;
326
 
=============================================================================
327
 
WARNING: $num_unused unused declarations.
328
 
  These can be found in $MODULE-unused.txt.
329
 
  They should be added to $MODULE-sections.txt in the appropriate place.
330
 
=============================================================================
331
 
EOF
 
331
        &LogWarning ($old_unused_file, 1, "$num_unused unused declarations.".
 
332
            "They should be added to $MODULE-sections.txt in the appropriate place.");
332
333
    }
333
334
 
334
335
    return &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 0);
378
379
        my $ret_type_pointer = $4;
379
380
 
380
381
        my ($param_num) = 0;
381
 
        my ($name);
382
382
        while ($declaration ne "") {
383
383
            if ($declaration =~ s/^[\s,]+//) {
384
384
                # skip whitespace and commas
386
386
 
387
387
            } elsif ($declaration =~ s/^void\s*[,\n]//) {
388
388
                if ($param_num != 0) {
389
 
                    print "WARNING: void used as parameter in function $symbol\n";
 
389
                    &LogWarning ($SymbolSourceFile{$symbol},$SymbolSourceLine{$symbol}, "void used as parameter in function $symbol");
390
390
                }
391
391
 
392
392
            } elsif ($declaration =~ s/^...\s*[,\n]//) {
397
397
            #                                $1                                                                                                                                    $2                             $3                                                           $4       $5
398
398
            } elsif ($declaration =~ s/^\s*((?:G_CONST_RETURN|G_GNUC_UNUSED|unsigned long|unsigned short|signed long|signed short|unsigned|signed|long|short|volatile|const)\s+)*((?:struct\b|enum\b)?\s*\w+)\s*((?:(?:const\b|restrict\b)?\s*\*?\s*(?:const\b|restrict\b)?\s*)*)(\w+)?\s*((?:\[\S*\])*)\s*[,\n]//) {
399
399
                my $pre         = defined($1) ? $1 : "";
400
 
                my $type        = $2;
 
400
                my $vtype       = $2;
401
401
                my $ptr         = defined($3) ? $3 : "";
402
402
                my $name        = defined($4) ? $4 : "";
403
403
 
404
 
                $pre  =~ s/\s+/ /g;
405
 
                $type =~ s/\s+/ /g;
406
 
                $ptr  =~ s/\s+/ /g;
407
 
                $ptr  =~ s/\s+$//;
 
404
                $pre   =~ s/\s+/ /g;
 
405
                $vtype =~ s/\s+/ /g;
 
406
                $ptr   =~ s/\s+/ /g;
 
407
                $ptr   =~ s/\s+$//;
408
408
                if ($ptr && $ptr !~ m/\*$/) { $ptr .= " "; }
409
409
 
410
410
                if (($name eq "") && $pre =~ m/^((un)?signed .*)\s?/ ) {
411
 
                    $name = $type;
412
 
                    $type = "$1";
413
 
                    $pre = "";
 
411
                    $name  = $vtype;
 
412
                    $vtype = "$1";
 
413
                    $pre   = "";
414
414
                }
415
415
 
416
 
                #print "$symbol: '$pre' '$type' '$ptr' '$name' \n";
 
416
                #print "$symbol: '$pre' '$vtype' '$ptr' '$name' \n";
417
417
 
418
418
                if ($name eq "") {
419
419
                    $name = "Param" . ($param_num + 1);
420
420
                }
421
 
                $output .= &OutputParam ($symbol, $name, $template_exists, 1,
422
 
                                         "");
 
421
                $output .= &OutputParam ($symbol, $name, $template_exists, 1, "");
423
422
 
424
423
            # Try to match parameters which are functions (keep in sync with gtkdoc-mkdb)
425
424
            #                              $1                                       $2          $3      $4                      $5                    $7             $8
426
425
            } elsif ($declaration =~ s/^(const\s+|G_CONST_RETURN\s+|unsigned\s+)*(struct\s+)?(\w+)\s*(\**)\s*(?:restrict\b)?\s*(const\s+)?\(\s*\*+\s*(\w+)\s*\)\s*\(([^)]*)\)\s*[,\n]//) {
427
 
                $name = $6;
 
426
                my $name = $6;
428
427
                $output .= &OutputParam ($symbol, $name, $template_exists, 1,
429
428
                                         "");
430
429
 
815
814
        my $type = $SymbolTypes{$symbol};
816
815
        if (!defined ($type)) {
817
816
            $type = "UNKNOWN";
818
 
            print "WARNING: Unused symbol $symbol has unknown type\n";
 
817
            &LogWarning ($SymbolSourceFile{$symbol},$SymbolSourceLine{$symbol}, "Unused symbol $symbol has unknown type.");
819
818
        }
820
819
 
821
820
    $output .= <<EOF;
928
927
                            } elsif ($declaration =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
929
928
                                # Ignore an empty or forward declaration.
930
929
                            } else {
931
 
                                print "WARNING: Structure $declaration_name has multiple definitions: $file:$.\n";
 
930
                                &LogWarning ($file, $., "Structure $declaration_name has multiple definitions.");
932
931
                            }
933
932
 
934
933
                        } else {
937
936
                            $DeclarationConditional{$declaration_name} = 1;
938
937
                        }
939
938
                    } else {
940
 
                        print "ERROR: $declaration_name has multiple definitions: $file:$.\n";
 
939
                        &LogWarning ($file, $., "$declaration_name has multiple definitions.");
941
940
                    }
942
941
                } else {
943
942
                    $Declarations{$declaration_name} = $declaration;
956
955
#############################################################################
957
956
# Function    : ReadSignalsFile
958
957
# Description : This reads in an existing file which contains information on
959
 
#               all GTK signals. It creates the arrays @SignalNames and
 
958
#               all GObject signals. It creates the arrays @SignalNames and
960
959
#               @SignalPrototypes containing info on the signals. The first
961
960
#               line of the SignalPrototype is the return type of the signal
962
961
#               handler. The remaining lines are the parameters passed to it.
1050
1049
#    print "Reading $docsfile\n";
1051
1050
    if (! -f $docsfile) {
1052
1051
        print "File doesn't exist: $docsfile\n";
1053
 
        return;
 
1052
        return 0;
1054
1053
    }
1055
1054
 
1056
 
    my $CurrentType = "";       # Type of symbol being read.
 
1055
    my $CurrentType = "";       # Type of symbol being read.
1057
1056
    my $CurrentSymbol = "";     # Name of symbol being read.
1058
1057
    my $SymbolDoc = "";         # Description of symbol being read.
1059
1058
    my @Params;                 # Parameter names and descriptions of current
1075
1074
                || $symbol eq "See_Also"
1076
1075
                || $symbol eq "Stability_Level") {
1077
1076
                $symbol = $docsfile . ":" . $symbol;
1078
 
#               print "Found symbol: $symbol\n";
1079
1077
            }
1080
1078
 
 
1079
            #print "Found symbol: $symbol\n";
 
1080
            # Remember file and line for the symbol
 
1081
            $SymbolSourceFile{$symbol} = $docsfile;
 
1082
            $SymbolSourceLine{$symbol} = $.;
 
1083
 
1081
1084
            # Canonicalize signal and argument names to have -, not _
1082
1085
            if ($type eq "ARG" || $type eq "SIGNAL") {
1083
1086
              $symbol =~ s/_/-/g;
1088
1091
                $SymbolDoc =~ s/\s+$//;
1089
1092
                $SymbolTypes{$CurrentSymbol} = $CurrentType;
1090
1093
                $SymbolDocs{$CurrentSymbol} = $SymbolDoc;
 
1094
 
1091
1095
                if ($CurrentParam >= 0) {
1092
1096
                    $SymbolParams{$CurrentSymbol} = [ @Params ];
1093
1097
                } else {
1149
1153
 
1150
1154
    # Remember to finish the current symbol doccs.
1151
1155
    if ($CurrentSymbol ne "") {
 
1156
 
1152
1157
        $SymbolDoc =~ s/\s+$//;
1153
1158
        $SymbolTypes{$CurrentSymbol} = $CurrentType;
1154
1159
        $SymbolDocs{$CurrentSymbol} = $SymbolDoc;
 
1160
 
1155
1161
        if ($CurrentParam >= 0) {
1156
1162
            $SymbolParams{$CurrentSymbol} = [ @Params ];
1157
1163
        } else {
1160
1166
    }
1161
1167
 
1162
1168
    close (DOCS);
 
1169
    return 1;
1163
1170
}
1164
1171
 
1165
1172
 
1208
1215
#############################################################################
1209
1216
# Function    : ReadArgsFile
1210
1217
# Description : This reads in an existing file which contains information on
1211
 
#               all GTK args. It creates the arrays @ArgObjects, @ArgNames,
 
1218
#               all GObject args. It creates the arrays @ArgObjects, @ArgNames,
1212
1219
#               @ArgTypes and @ArgFlags containing info on the args.
1213
1220
# Arguments   : $file - the file containing the arg information.
1214
1221
#############################################################################
1274
1281
 
1275
1282
#############################################################################
1276
1283
# Function    : CheckIsObject
1277
 
# Description : Returns 1 if the given name is a GtkObject or a subclass.
 
1284
# Description : Returns 1 if the given name is a GObject or a subclass.
1278
1285
#               It uses the global @Objects array.
1279
1286
#               Note that the @Objects array only contains classes in the
1280
 
#               current module and their ancestors - not all GTK classes.
 
1287
#               current module and their ancestors - not all GObject classes.
1281
1288
# Arguments   : $name - the name to check.
1282
1289
#############################################################################
1283
1290