4 # gtk-doc - GTK DocBook documentation generator.
5 # Copyright (C) 1998 Damon Chaplin
7 # This program is free software; you can redistribute it and/or modify
8 # it under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 2 of the License, or
10 # (at your option) any later version.
12 # This program is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with this program; if not, write to the Free Software
19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 #############################################################################
23 # Script : gtkdoc-mktmpl
24 # Description : This creates or updates the template files which contain the
25 # manually-edited documentation. (A 'template' is a simple text
26 # form which is filled in with the description of a function,
27 # macro, enum, or struct. For functions and macros it also
28 # contains fields for describing the parameters.)
30 # This script reads in the existing templates, found in
31 # tmpl/*.sgml, moves these files to tmpl/*.sgml.bak, and then
32 # recreates the .sgml files according to the structure given in
33 # the file $MODULE-sections.txt.
35 # Any new templates added, or new function parameters, are
36 # marked with 'FIXME' so you can do a grep to see which parts
39 # Any templates which are no longer used (i.e. they are remove
40 # from $MODULE-sections.txt) are placed in the file
41 # tmpl/$MODULE-unused.sgml. If they are included again later
42 # they are automatically copied back into position.
43 # If you are certain that these templates will never be used
44 # again you can delete them from tmpl/$MODULE-unused.sgml.
46 # Any parameters to functions which are no longer used are
47 # separated from the rest of the parameters with the line
48 # '<!-- # Unused Parameters # -->'. It may be that the parameter
49 # name has just been changed, in which case you can copy the
50 # description to the parameter with the new name. You can delete
51 # the unused parameter descriptions when no longer needed.
52 #############################################################################
57 push @INC, '@PACKAGE_DATA_DIR@';
58 require "gtkdoc-common.pl";
62 # name of documentation module
68 my $ONLY_SECTION_TMPL;
70 my %optctl = ('module' => \$MODULE,
71 'flag-changes' => \$FLAG_CHANGES,
72 'output-dir' => \$TMPL_DIR,
73 'only-section-tmpl' => \$ONLY_SECTION_TMPL,
74 'version' => \$PRINT_VERSION,
75 'help' => \$PRINT_HELP);
76 GetOptions(\%optctl, "module=s", "flag-changes!", "output-dir:s", "only-section-tmpl!", "version", "help");
89 gtkdoc-mktmpl version @VERSION@ - generate documentation templates
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
103 # The directory containing the template files.
104 $TMPL_DIR = $TMPL_DIR ? $TMPL_DIR : "$ROOT_DIR/tmpl";
106 # This file contains the object hierarchy.
107 my $OBJECT_TREE_FILE = "$ROOT_DIR/$MODULE.hierarchy";
109 # The file containing signal handler prototype information.
110 my $SIGNALS_FILE = "$ROOT_DIR/$MODULE.signals";
112 # The file containing Arg information.
113 my $ARGS_FILE = "$ROOT_DIR/$MODULE.args";
115 # Set the flag to indicate changes, if requested.
116 my $CHANGES_FLAG = $FLAG_CHANGES ? "FIXME" : "";
118 # These global arrays store information on signals. Each signal has an entry
119 # in each of these arrays at the same index, like a multi-dimensional array.
120 my @SignalObjects; # The GtkObject which emits the signal.
121 my @SignalNames; # The signal name.
122 my @SignalReturns; # The return type.
123 my @SignalFlags; # Flags for the signal
124 my @SignalPrototypes; # The rest of the prototype of the signal handler.
126 # These global arrays store information on Args. Each Arg has an entry
127 # in each of these arrays at the same index, like a multi-dimensional array.
128 my @ArgObjects; # The GtkObject which has the Arg.
129 my @ArgNames; # The Arg name.
130 my @ArgTypes; # The Arg type - gint, GtkArrowType etc.
131 my @ArgFlags; # How the Arg can be used - readable/writable etc.
133 # These global hashes store declaration info keyed on a symbol name.
135 my %DeclarationTypes;
136 my %DeclarationConditional;
137 my %DeclarationOutput;
139 # These global hashes store the existing documentation.
143 my %SymbolSourceFile;
144 my %SymbolSourceLine;
146 # These global arrays store GObject and subclasses and the hierarchy.
150 &ReadSignalsFile ($SIGNALS_FILE);
151 &ReadArgsFile ($ARGS_FILE);
152 &ReadObjectHierarchy;
154 &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-decl.txt", 0);
155 if (-f "$ROOT_DIR/$MODULE-overrides.txt") {
156 &ReadDeclarationsFile ("$ROOT_DIR/$MODULE-overrides.txt", 1);
158 &ReadExistingTemplates;
162 if (&UpdateTemplates ("$ROOT_DIR/$MODULE-sections.txt")) {
165 &OutputUnusedTemplates;
166 if (&CheckAllDeclarationsOutput) {
170 if ($changed || ! -e "$ROOT_DIR/tmpl.stamp") {
171 open (TIMESTAMP, ">$ROOT_DIR/tmpl.stamp")
172 || die "Can't create $ROOT_DIR/tmpl.stamp";
173 print (TIMESTAMP "timestamp");
177 #############################################################################
178 # Function : ReadExistingTemplates
179 # Description : This reads in all the existing documentation, into the global
180 # variables %SymbolDocs, %SymbolTypes, and %SymbolParams (a
183 #############################################################################
185 sub ReadExistingTemplates {
190 # Read the unused docs first, so they get overridden by any real docs.
191 # (though this shouldn't happen often).
192 my $unused_doc = "$TMPL_DIR/$MODULE-unused.sgml";
193 if (-e $unused_doc) {
194 &ReadTemplateFile ($unused_doc, 0);
197 while (<$TMPL_DIR/*.sgml>) {
198 # print "Reading $_\n";
199 if ($_ eq $unused_doc) {
200 # print "skipping $unused_doc\n";
202 &ReadTemplateFile ($_, 0);
208 #############################################################################
209 # Function : UpdateTemplates
210 # Description : This collects the output for each section of the docs, and
211 # outputs each file when the end of the section is found.
212 # Arguments : $file - the file containing the sections of the docs.
213 #############################################################################
215 sub UpdateTemplates {
217 # print "Reading: $file\n";
220 || die "Can't open $file";
222 # Create the top output directory if it doesn't exist.
223 if (! -e $TMPL_DIR) {
224 mkdir ("$TMPL_DIR", 0777)
225 || die "Can't create directory: $TMPL_DIR";
237 } elsif (m/^<SECTION>/) {
240 } elsif (m/^<SUBSECTION\s*(.*)>/i) {
244 } elsif (m/^<TITLE>(.*)<\/TITLE>/) {
246 # print "Section: $title\n";
248 } elsif (m/^<FILE>(.*)<\/FILE>/) {
251 } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
254 } elsif (m/^<\/SECTION>/) {
258 # print "End of section: $title\n";
260 $filename =~ s/\s/_/g;
261 $filename .= ".sgml";
263 if (&OutputTemplateFile ($filename, $title, \$output)) {
270 } elsif (m/^(\S+)/) {
272 # print " Symbol: $symbol\n";
274 my $declaration = $Declarations{$1};
275 if (defined ($declaration)) {
276 # We don't want templates for standard macros/functions of
277 # GObjects or private declarations.
278 if ($subsection ne "Standard" && $subsection ne "Private") {
279 $output .= &OutputDeclaration ($DeclarationTypes {$symbol},
280 $symbol, $declaration);
282 $output .= &OutputSignalTemplates ($symbol);
283 $output .= &OutputArgTemplates ($symbol);
286 # Note that the declaration has been output.
287 $DeclarationOutput{$symbol} = 1;
289 if ($declaration eq '##conditional##') {
290 # print "Conditional $DeclarationTypes{$symbol}\n";
294 &LogWarning ($file, $., "No declaration found for: $1");
304 #############################################################################
305 # Function : CheckAllDeclarationsOutput
306 # Description : This steps through all the declarations that were loaded, and
307 # makes sure that each one has been output, by checking the
308 # corresponding flag in the %DeclarationOutput hash. It is
309 # intended to check that any new declarations in new versions
310 # of the module get added to the $MODULE-sections.txt file.
312 #############################################################################
314 sub CheckAllDeclarationsOutput {
317 my $old_unused_file = "$ROOT_DIR/$MODULE-unused.txt";
318 my $new_unused_file = "$ROOT_DIR/$MODULE-unused.new";
320 open (UNUSED, ">$new_unused_file")
321 || die "Can't open $new_unused_file";
323 foreach $symbol (sort keys (%Declarations)) {
324 if (!defined ($DeclarationOutput{$symbol})) {
325 print (UNUSED "$symbol\n");
330 if ($num_unused != 0) {
331 &LogWarning ($old_unused_file, 1, "$num_unused unused declarations.".
332 "They should be added to $MODULE-sections.txt in the appropriate place.");
335 return &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 0);
339 #############################################################################
340 # Function : OutputDeclaration
341 # Description : This returns the template for one symbol & declaration.
342 # Note that it uses the global %SymbolDocs and %SymbolParams to
343 # lookup any existing documentation.
344 # Arguments : $type - the type of the symbol ('FUNCTION'/'MACRO' etc.)
345 # $symbol - the symbol name.
346 # $declaration - the declaration of the symbol.
347 #############################################################################
349 sub OutputDeclaration {
350 my ($type, $symbol, $declaration) = @_;
353 #print "Outputting $type: $symbol\n";
355 # See if symbol already has a description.
356 my ($symbol_desc) = $SymbolDocs{$symbol};
357 my ($template_exists);
358 if (defined ($symbol_desc)) {
359 $template_exists = 1;
360 $symbol_desc =~ s/\s+$//;
362 $template_exists = 0;
363 $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>";
367 <!-- ##### $type $symbol ##### -->
372 # For functions, function typedefs and macros, we output the arguments.
373 # For functions and function typedefs we also output the return value.
374 if ($type eq "FUNCTION" || $type eq "USER_FUNCTION") {
375 # Take out the return type
376 $declaration =~ s/<RETURNS>\s*((const\s+|G_CONST_RETURN\s+|unsigned\s+|struct\s+|enum\s+)*)(\w+)\s*(\**\s*(const|G_CONST_RETURN)?\s*\**\s*(restrict)?\s*)<\/RETURNS>\n//;
377 my $ret_type_modifier = defined($1) ? $1 : "";
379 my $ret_type_pointer = $4;
381 my @fields = ParseFunctionDeclaration($declaration);
383 for (my $i = 0; $i <= $#fields; $i += 2) {
384 my $field_name = $fields[$i];
385 $output .= &OutputParam ($symbol, $field_name, $template_exists, 1, "");
388 if ($ret_type ne "void" || $ret_type_modifier || $ret_type_pointer) {
389 $output .= &OutputParam ($symbol, "Returns", $template_exists, 1, "");
392 $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
393 $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
394 $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
395 $output .= &OutputOldParams ($symbol);
399 if ($type eq "MACRO") {
400 my @fields = ParseMacroDeclaration($declaration);
402 for (my $i = 0; $i <= $#fields; $i +=2) {
403 my $field_name = $fields[$i];
405 $output .= &OutputParam ($symbol, $field_name, $template_exists,
408 $output .= &OutputParam ($symbol, "Returns", $template_exists, 0, "");
409 $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
410 $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
411 $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
412 $output .= &OutputOldParams ($symbol);
416 if ($type eq "STRUCT") {
417 my $is_object_struct = CheckIsObject ($symbol);
418 my @fields = ParseStructDeclaration($declaration, $is_object_struct, 1);
420 for (my $i = 0; $i <= $#fields; $i += 2) {
421 my $field_name = $fields[$i];
422 $output .= &OutputParam ($symbol, $field_name, $template_exists, 1, "");
424 $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
425 $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
426 $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
429 if ($type eq "ENUM") {
430 my @members = ParseEnumDeclaration($declaration);
432 for my $member (@members) {
433 $output .= &OutputParam ($symbol, $member, $template_exists, 1, "");
435 $output .= &OutputParam ($symbol, "Deprecated", $template_exists, 0, "");
436 $output .= &OutputParam ($symbol, "Since", $template_exists, 0, "");
437 $output .= &OutputParam ($symbol, "Stability", $template_exists, 0, "");
442 # Remove the used docs from the hashes.
443 if ($template_exists) {
444 delete $SymbolDocs{$symbol};
445 delete $SymbolParams{$symbol};
452 #############################################################################
453 # Function : OutputParam
454 # Description : This outputs the part of a template for one parameter.
455 # It first checks if the parameter is already described, and if
456 # so it uses that description, and clears it so it isn't output
458 # Arguments : $symbol - the symbol (function or macro) name.
459 # $param_to_output - the parameter to add.
460 # $template_exists - TRUE if the template already existed in
461 # template files. If it did, then we will flag any changes
463 # $force_output - TRUE if the parameter should be output even
464 # if it didn't already exist in the template. (The return
465 # values of macros are added manually if required, and so we
466 # never add it here - we only copy it if it already exists.)
467 # $default_description - the default description of the
468 # parameter to be used if it doesn't already exist. (Signal
469 # handlers have a few common parameters.)
470 #############################################################################
473 my ($symbol, $param_to_output, $template_exists,
474 $force_output, $default_description) = @_;
477 my ($params) = $SymbolParams{$symbol};
478 if (defined ($params)) {
479 for ($j = 0; $j <= $#$params; $j += 2) {
480 my $param_name = $$params[$j];
481 my $param_desc = $$params[$j + 1];
483 if ($param_name eq $param_to_output) {
484 $param_desc =~ s/\s+$//;
486 $$params[$j + 1] = "";
487 return "\@$param_name: $param_desc\n";
492 # If the template was already in a file, flag the new parameter.
493 # If not, the template itself will be flagged, so we don't need to flag
494 # all the new parameters as well.
496 if ($default_description ne "") {
497 $default_description =~ s/\s+$//;
498 return "\@$param_to_output: $default_description\n";
500 if ($template_exists) {
501 return "\@$param_to_output: $CHANGES_FLAG\n";
503 return "\@$param_to_output: \n";
511 #############################################################################
512 # Function : OutputOldParams
513 # Description : This returns all the existing documentation for parameters of
514 # the given function/macro/signal symbol which are unused, with
515 # a comment before them.
516 # Arguments : $symbol - the symbol (function/macro/signal) name.
517 #############################################################################
519 sub OutputOldParams {
523 my ($params) = $SymbolParams{$symbol};
524 if (defined ($params)) {
526 for ($j = 0; $j <= $#$params; $j += 2) {
527 my $param_name = $$params[$j];
528 my $param_desc = $$params[$j + 1];
530 if ($param_name ne "") {
531 $param_desc =~ s/\s+$//;
533 # There's no point keeping it if it has no docs.
534 if ($param_desc ne "") {
535 $output .= "\@$param_name: $param_desc\n";
541 $output = "<!-- # Unused Parameters # -->\n" . $output;
547 #############################################################################
548 # Function : OutputTemplateFile
549 # Description : This outputs one template file.
550 # Arguments : $file - the basename of the file to output.
551 # $title - the title from the $MODULE-sections.txt file. This
552 # will be overridden by any title given in the template file.
553 # $output - reference to the templates to output.
554 #############################################################################
556 sub OutputTemplateFile {
557 my ($file, $title, $output) = @_;
559 my ($short_desc, $long_desc, $see_also, $stability);
561 if (defined ($SymbolDocs{"$TMPL_DIR/$file:Title"})) {
562 $title = $SymbolDocs{"$TMPL_DIR/$file:Title"};
563 delete $SymbolDocs{"$TMPL_DIR/$file:Title"};
565 if (defined ($SymbolDocs{"$TMPL_DIR/$file:Short_Description"})) {
566 $short_desc = $SymbolDocs{"$TMPL_DIR/$file:Short_Description"};
567 delete $SymbolDocs{"$TMPL_DIR/$file:Short_Description"};
571 if (defined ($SymbolDocs{"$TMPL_DIR/$file:Long_Description"})) {
572 $long_desc = $SymbolDocs{"$TMPL_DIR/$file:Long_Description"};
573 delete $SymbolDocs{"$TMPL_DIR/$file:Long_Description"};
575 $long_desc = "<para>\n\n</para>\n";
577 if (defined ($SymbolDocs{"$TMPL_DIR/$file:See_Also"})) {
578 $see_also = $SymbolDocs{"$TMPL_DIR/$file:See_Also"};
579 delete $SymbolDocs{"$TMPL_DIR/$file:See_Also"};
581 $see_also = "<para>\n\n</para>\n";
583 if (defined ($SymbolDocs{"$TMPL_DIR/$file:Stability_Level"})) {
584 $stability = $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
585 delete $SymbolDocs{"$TMPL_DIR/$file:Stability_Level"};
591 my $old_tmpl_file = "$TMPL_DIR/$file";
592 my $new_tmpl_file = "$TMPL_DIR/$file.new";
594 open (OUTPUT, ">$new_tmpl_file")
595 || die "Can't create $new_tmpl_file";
597 print (OUTPUT <<EOF);
598 <!-- ##### SECTION Title ##### -->
601 <!-- ##### SECTION Short_Description ##### -->
604 <!-- ##### SECTION Long_Description ##### -->
607 <!-- ##### SECTION See_Also ##### -->
610 <!-- ##### SECTION Stability_Level ##### -->
615 print (OUTPUT $$output) unless $ONLY_SECTION_TMPL;
618 return &UpdateFileIfChanged ($old_tmpl_file, $new_tmpl_file, 1);
622 #############################################################################
623 # Function : OutputSignalTemplates
624 # Description : Outputs templates for signal handlers.
625 # Arguments : $title - the title from the $MODULE-sections.txt file. If the
626 # file is describing a GtkObject subclass, the title should
627 # be the name of the class, e.g. 'GtkButton'.
628 #############################################################################
630 sub OutputSignalTemplates {
634 my ($i, $template_exists);
635 for ($i = 0; $i <= $#SignalObjects; $i++) {
636 if ($SignalObjects[$i] eq $title) {
637 # print "Found signal: $SignalObjects[$i]\n";
638 my ($symbol) = "$SignalObjects[$i]::$SignalNames[$i]";
640 # See if symbol already has a description.
641 my ($symbol_desc) = $SymbolDocs{$symbol};
642 if (defined ($symbol_desc)) {
643 $template_exists = 1;
644 $symbol_desc =~ s/\s+$//;
645 delete $SymbolDocs{$symbol};
647 $template_exists = 0;
648 $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>";
652 <!-- ##### SIGNAL $symbol ##### -->
656 my $sourceparams = $SymbolParams{$symbol};
657 my @params = split ("[,\n]", $SignalPrototypes[$i]);
659 for ($j = 0; $j <= $#params; $j++) {
660 my $param = $params[$j];
663 if ($param =~ m/^\s*$/) { next; }
664 if ($param =~ m/^void$/) { next; }
666 if ($param =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)?\s*$/) {
667 if (defined ($sourceparams)) {
668 $name = $$sourceparams[2 * $j];
673 if (!defined ($name)) {
674 $name = "Param" . ($j + 1);
678 $output .= &OutputParam ($symbol, $name,
680 "the object which received the signal.");
682 $output .= &OutputParam ($symbol, $name,
683 $template_exists, 1, "");
688 if ($SignalReturns[$i] ne "void") {
689 $output .= &OutputParam ($symbol, "Returns", $template_exists,
692 $output .= &OutputOldParams ($symbol);
700 #############################################################################
701 # Function : OutputArgTemplates
702 # Description : Outputs templates for Args.
703 # Arguments : $title - the title from the $MODULE-sections.txt file. If the
704 # file is describing a GtkObject subclass, the title should
705 # be the name of the class, e.g. 'GtkButton'.
706 #############################################################################
708 sub OutputArgTemplates {
713 for ($i = 0; $i <= $#ArgObjects; $i++) {
714 if ($ArgObjects[$i] eq $title) {
715 # print "Found arg: $ArgObjects[$i]\n";
716 # I've only used one colon so we don't clash with signals.
717 my ($symbol) = "$ArgObjects[$i]:$ArgNames[$i]";
719 # See if symbol already has a description.
720 my ($symbol_desc) = $SymbolDocs{$symbol};
721 if (defined ($symbol_desc)) {
722 delete $SymbolDocs{$symbol};
723 $symbol_desc =~ s/\s+$//;
725 $symbol_desc = "<para>\n$CHANGES_FLAG\n</para>";
729 <!-- ##### ARG $symbol ##### -->
739 #############################################################################
740 # Function : OutputUnusedTemplates
741 # Description : This saves any unused documentation into $MODULE-unused.sgml.
743 #############################################################################
745 sub OutputUnusedTemplates {
746 my ($old_unused_file) = "$TMPL_DIR/$MODULE-unused.sgml";
747 my ($new_unused_file) = "$TMPL_DIR/$MODULE-unused.new";
749 open (UNUSED, ">$new_unused_file")
750 || die "Can't open file: $new_unused_file";
753 my ($symbol, $symbol_desc);
754 for $symbol (sort keys %SymbolDocs) {
755 $symbol_desc = $SymbolDocs{$symbol};
757 # print "Unused: $symbol\n";
759 my $type = $SymbolTypes{$symbol};
760 if (!defined ($type)) {
762 &LogWarning ($SymbolSourceFile{$symbol},$SymbolSourceLine{$symbol}, "Unused symbol $symbol has unknown type.");
766 <!-- ##### $type $symbol ##### -->
771 my ($params) = $SymbolParams{$symbol};
772 if (defined ($params)) {
774 for ($j = 0; $j <= $#$params; $j += 2) {
775 my $param_name = $$params[$j];
776 my $param_desc = $$params[$j + 1];
777 $param_desc =~ s/\s+$//;
778 $output .= "\@$param_name: $param_desc\n";
784 print UNUSED $output;
787 &UpdateFileIfChanged ($old_unused_file, $new_unused_file, 1);
791 #############################################################################
792 # LIBRARY FUNCTIONS - These functions are used in both gtkdoc-mkdb and
793 # gtkdoc-mktmpl and should eventually be moved to a
795 #############################################################################
797 #############################################################################
798 # Function : ReadDeclarationsFile
799 # Description : This reads in a file containing the function/macro/enum etc.
802 # Note that in some cases there are several declarations with
803 # the same name, e.g. for conditional macros. In this case we
804 # set a flag in the %DeclarationConditional hash so the
805 # declaration is not shown in the docs.
807 # If a macro and a function have the same name, e.g. for
808 # gtk_object_ref, the function declaration takes precedence.
810 # Some opaque structs are just declared with 'typedef struct
811 # _name name;' in which case the declaration may be empty.
812 # The structure may have been found later in the header, so
813 # that overrides the empty declaration.
815 # Arguments : $file - the declarations file to read
816 # $override - if declarations in this file should override
817 # any current declaration.
818 #############################################################################
820 sub ReadDeclarationsFile {
821 my ($file, $override) = @_;
823 if ($override == 0) {
825 %DeclarationTypes = ();
826 %DeclarationConditional = ();
827 %DeclarationOutput = ();
831 || die "Can't open $file";
832 my $declaration_type = "";
833 my $declaration_name;
836 if (!$declaration_type) {
838 $declaration_type = $1;
839 $declaration_name = "";
840 # print "Found declaration: $declaration_type\n";
844 if (m%^<NAME>(.*)</NAME>%) {
845 $declaration_name = $1;
846 } elsif (m%<DEPRECATED/>%) {
847 # do nothing, just skip the line; we handle this
849 } elsif (m%^</$declaration_type>%) {
850 # print "Found end of declaration: $declaration_name\n";
851 # Check that the declaration has a name
852 if ($declaration_name eq "") {
853 print "ERROR: $declaration_type has no name $file:$.\n";
856 # Check if the symbol is already defined.
857 if (defined ($Declarations{$declaration_name})
859 # Function declarations take precedence.
860 if ($DeclarationTypes{$declaration_name} eq 'FUNCTION') {
862 } elsif ($declaration_type eq 'FUNCTION') {
863 $Declarations{$declaration_name} = $declaration;
864 $DeclarationTypes{$declaration_name} = $declaration_type;
865 } elsif ($DeclarationTypes{$declaration_name}
866 eq $declaration_type) {
867 # If the existing declaration is empty, or is just a
868 # forward declaration of a struct, override it.
869 if ($declaration_type eq 'STRUCT') {
870 if ($Declarations{$declaration_name} =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
871 $Declarations{$declaration_name} = $declaration;
872 } elsif ($declaration =~ m/^\s*(struct\s+\w+\s*;)?\s*$/) {
873 # Ignore an empty or forward declaration.
875 &LogWarning ($file, $., "Structure $declaration_name has multiple definitions.");
879 # set flag in %DeclarationConditional hash for
880 # multiply defined macros/typedefs.
881 $DeclarationConditional{$declaration_name} = 1;
884 &LogWarning ($file, $., "$declaration_name has multiple definitions.");
887 $Declarations{$declaration_name} = $declaration;
888 $DeclarationTypes{$declaration_name} = $declaration_type;
890 $declaration_type = "";
900 #############################################################################
901 # Function : ReadSignalsFile
902 # Description : This reads in an existing file which contains information on
903 # all GObject signals. It creates the arrays @SignalNames and
904 # @SignalPrototypes containing info on the signals. The first
905 # line of the SignalPrototype is the return type of the signal
906 # handler. The remaining lines are the parameters passed to it.
907 # The last parameter, "gpointer user_data" is always the same
908 # so is not included.
909 # Arguments : $file - the file containing the signal handler prototype
911 #############################################################################
913 sub ReadSignalsFile {
921 my $signal_prototype;
923 # Reset the signal info.
928 @SignalPrototypes = ();
933 if (!open (INPUT, $file)) {
934 warn "Can't open $file - skipping signals\n";
943 $signal_returns = "";
944 $signal_prototype = "";
947 if (m/^<NAME>(.*)<\/NAME>/) {
949 if ($signal_name =~ m/^(.*)::(.*)$/) {
951 ($signal_name = $2) =~ s/_/-/g;
952 # print "Found signal: $signal_name\n";
954 print "Invalid signal name: $signal_name\n";
956 } elsif (m/^<RETURNS>(.*)<\/RETURNS>/) {
957 $signal_returns = $1;
958 } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
960 } elsif (m%^</SIGNAL>%) {
961 # print "Found end of signal: ${signal_object}::${signal_name}\nReturns: ${signal_returns}\n${signal_prototype}";
962 push (@SignalObjects, $signal_object);
963 push (@SignalNames, $signal_name);
964 push (@SignalReturns, $signal_returns);
965 push (@SignalFlags, $signal_flags);
966 push (@SignalPrototypes, $signal_prototype);
969 $signal_prototype .= $_;
977 #############################################################################
978 # Function : ReadTemplateFile
979 # Description : This reads in the manually-edited documentation file
980 # corresponding to the file currently being created, so we can
981 # insert the documentation at the appropriate places.
982 # It outputs %SymbolTypes, %SymbolDocs and %SymbolParams, which
983 # is a hash of arrays.
984 # NOTE: This function is duplicated in gtkdoc-mkdb (but
985 # slightly different).
986 # Arguments : $docsfile - the template file to read in.
987 # $skip_unused_params - 1 if the unused parameters should be
989 #############################################################################
991 sub ReadTemplateFile {
992 my ($docsfile, $skip_unused_params) = @_;
994 # print "Reading $docsfile\n";
995 if (! -f $docsfile) {
996 print "File doesn't exist: $docsfile\n";
1000 my $CurrentType = ""; # Type of symbol being read.
1001 my $CurrentSymbol = ""; # Name of symbol being read.
1002 my $SymbolDoc = ""; # Description of symbol being read.
1003 my @Params; # Parameter names and descriptions of current
1004 # function/macro/function typedef.
1005 my $CurrentParam = -1; # Index of parameter currently being read.
1006 # Note that the param array contains pairs
1007 # of param name & description.
1008 my $InUnusedParameters = 0; # True if we are reading in the unused params.
1010 open (DOCS, $docsfile)
1011 || die "Can't open file $docsfile: $!";
1013 if (m/^<!-- ##### ([A-Z_]+) (\S+) ##### -->/) {
1016 if ($symbol eq "Title"
1017 || $symbol eq "Short_Description"
1018 || $symbol eq "Long_Description"
1019 || $symbol eq "See_Also"
1020 || $symbol eq "Stability_Level") {
1021 $symbol = $docsfile . ":" . $symbol;
1024 #print "Found symbol: $symbol\n";
1025 # Remember file and line for the symbol
1026 $SymbolSourceFile{$symbol} = $docsfile;
1027 $SymbolSourceLine{$symbol} = $.;
1029 # Canonicalize signal and argument names to have -, not _
1030 if ($type eq "ARG" || $type eq "SIGNAL") {
1034 # Store previous symbol, but remove any trailing blank lines.
1035 if ($CurrentSymbol ne "") {
1036 $SymbolDoc =~ s/\s+$//;
1037 $SymbolTypes{$CurrentSymbol} = $CurrentType;
1038 $SymbolDocs{$CurrentSymbol} = $SymbolDoc;
1040 if ($CurrentParam >= 0) {
1041 $SymbolParams{$CurrentSymbol} = [ @Params ];
1043 # Delete any existing params in case we are overriding a
1044 # previously read template.
1045 delete $SymbolParams{$CurrentSymbol};
1048 $CurrentType = $type;
1049 $CurrentSymbol = $symbol;
1051 $InUnusedParameters = 0;
1055 } elsif (m/^<!-- # Unused Parameters # -->/) {
1056 $InUnusedParameters = 1;
1060 # Workaround for an old bug that left a mess in the templates.
1061 # This happened with macros with args spread over several lines.
1063 # Skip the next line.
1068 # Workaround for an old bug that left '@:' at start of lines.
1074 # Check if param found. Need to handle "..." and "format...".
1075 if (s/^\@([\w\.]+):\040?//) {
1076 my $param_name = $1;
1077 # Allow variations of 'Returns'
1078 if ($param_name =~ m/^[Rr]eturns?$/) {
1079 $param_name = "Returns";
1081 # print "Found param: $param_name\n";
1082 push (@Params, $param_name);
1088 # When outputting the DocBook we skip unused parameters.
1089 if (!$InUnusedParameters || !$skip_unused_params) {
1090 if ($CurrentParam >= 0) {
1091 $Params[$CurrentParam] .= $_;
1099 # Remember to finish the current symbol doccs.
1100 if ($CurrentSymbol ne "") {
1102 $SymbolDoc =~ s/\s+$//;
1103 $SymbolTypes{$CurrentSymbol} = $CurrentType;
1104 $SymbolDocs{$CurrentSymbol} = $SymbolDoc;
1106 if ($CurrentParam >= 0) {
1107 $SymbolParams{$CurrentSymbol} = [ @Params ];
1109 delete $SymbolParams{$CurrentSymbol};
1118 #############################################################################
1119 # Function : ReadObjectHierarchy
1120 # Description : This reads in the $MODULE-hierarchy.txt file containing all
1121 # the GtkObject subclasses described in this module (and their
1123 # It places them in the @Objects array, and places their level
1124 # in the widget hierarchy in the @ObjectLevels array, at the
1125 # same index. GtkObject, the root object, has a level of 1.
1127 # FIXME: the version in gtkdoc-mkdb also generates tree_index.sgml
1128 # as it goes along, this should be split out into a separate
1132 #############################################################################
1134 sub ReadObjectHierarchy {
1138 if (! -f $OBJECT_TREE_FILE) {
1141 if (!open (INPUT, $OBJECT_TREE_FILE)) {
1142 warn "Can't open $OBJECT_TREE_FILE - skipping object tree\n";
1148 my $level = (length($`)) / 2 + 1;
1149 # print ("Level: $level Object: $object\n");
1151 push (@Objects, $object);
1152 push (@ObjectLevels, $level);
1160 #############################################################################
1161 # Function : ReadArgsFile
1162 # Description : This reads in an existing file which contains information on
1163 # all GObject args. It creates the arrays @ArgObjects, @ArgNames,
1164 # @ArgTypes and @ArgFlags containing info on the args.
1165 # Arguments : $file - the file containing the arg information.
1166 #############################################################################
1177 # Reset the signal info.
1186 if (!open (INPUT, $file)) {
1187 warn "Can't open $file - skipping args\n";
1200 if (m/^<NAME>(.*)<\/NAME>/) {
1202 if ($arg_name =~ m/^(.*)::(.*)$/) {
1204 ($arg_name = $2) =~ s/_/-/g;
1205 # print "Found arg: $arg_name\n";
1207 print "Invalid arg name: $arg_name\n";
1209 } elsif (m/^<TYPE>(.*)<\/TYPE>/) {
1211 } elsif (m/^<FLAGS>(.*)<\/FLAGS>/) {
1213 } elsif (m%^</ARG>%) {
1214 # print "Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n";
1215 push (@ArgObjects, $arg_object);
1216 push (@ArgNames, $arg_name);
1217 push (@ArgTypes, $arg_type);
1218 push (@ArgFlags, $arg_flags);
1227 #############################################################################
1228 # Function : CheckIsObject
1229 # Description : Returns 1 if the given name is a GObject or a subclass.
1230 # It uses the global @Objects array.
1231 # Note that the @Objects array only contains classes in the
1232 # current module and their ancestors - not all GObject classes.
1233 # Arguments : $name - the name to check.
1234 #############################################################################
1240 foreach $object (@Objects) {
1241 if ($object eq $name) {