diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.win_make.in | 2 | ||||
| -rw-r--r-- | doc/Makefile.win_nmake.in | 2 | ||||
| -rw-r--r-- | doc/config.doc | 22 | ||||
| -rw-r--r-- | doc/install.doc | 3 | ||||
| -rw-r--r-- | doc/language.doc | 24 | ||||
| -rw-r--r-- | doc/language.tpl | 20 | ||||
| -rw-r--r-- | doc/translator.pl | 197 |
7 files changed, 249 insertions, 21 deletions
diff --git a/doc/Makefile.win_make.in b/doc/Makefile.win_make.in index 7951ed8..3161b31 100644 --- a/doc/Makefile.win_make.in +++ b/doc/Makefile.win_make.in @@ -13,7 +13,7 @@ # input used in their production; they are not affected by this license. all: language FORCE - @xcopy /y /s /q /i ..\examples ..\html\examples + @xcopy /s /q /i ..\examples ..\html\examples set DOXYGEN_DOCDIR=. & \ set VERSION=$(VERSION) & \ $(DOXYGEN)\bin\doxygen diff --git a/doc/Makefile.win_nmake.in b/doc/Makefile.win_nmake.in index bef074a..05820b0 100644 --- a/doc/Makefile.win_nmake.in +++ b/doc/Makefile.win_nmake.in @@ -13,7 +13,7 @@ # input used in their production; they are not affected by this license. all: language FORCE - @xcopy /y /s /q /i ..\examples ..\html\examples + @xcopy /s /q /i ..\examples ..\html\examples set DOXYGEN_DOCDIR=. set VERSION=$(VERSION) $(DOXYGEN)\bin\doxygen diff --git a/doc/config.doc b/doc/config.doc index 44c51b7..64facc2 100644 --- a/doc/config.doc +++ b/doc/config.doc @@ -93,9 +93,11 @@ followed by the descriptions of the tags grouped by category. <li> \refitem cfg_example_recursive EXAMPLE_RECURSIVE <li> \refitem cfg_exclude EXCLUDE <li> \refitem cfg_exclude_patterns EXCLUDE_PATTERNS +<li> \refitem cfg_exclude_symlinks EXCLUDE_SYMLINKS <li> \refitem cfg_expand_as_defined EXPAND_AS_DEFINED <li> \refitem cfg_expand_only_predef EXPAND_ONLY_PREDEF <li> \refitem cfg_ext_doc_paths EXT_DOC_PATHS +<li> \refitem cfg_external_groups EXTERNAL_GROUPS <li> \refitem cfg_extra_packages EXTRA_PACKAGES <li> \refitem cfg_extract_all EXTRACT_ALL <li> \refitem cfg_extract_local_classes EXTRACT_LOCAL_CLASSES @@ -567,8 +569,11 @@ followed by the descriptions of the tags grouped by category. If the value of the \c INPUT tag contains directories, you can use the \c FILE_PATTERNS tag to specify one or more wildcard patterns (like \c *.cpp and \c *.h ) to filter out the source-files - in the directories. If left blank all files are included - (i.e. wildcard <tt>*</tt>). + in the directories. If left blank the following patterns are tested: + <code> + *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp + *.h++ *.idl *.odl + </code> \anchor cfg_recursive <dt>\c RECURSIVE <dd> @@ -584,6 +589,12 @@ followed by the descriptions of the tags grouped by category. excluded from the \c INPUT source files. This way you can easily exclude a subdirectory from a directory tree whose root is specified with the \c INPUT tag. +\anchor cfg_exclude_symlinks +<dt>\c EXCLUDE_SYMLINKS <dd> + \addindex EXCLUDE_SYMLINKS + The \c EXCLUDE_SYMLINKS tag can be used select whether or not files or directories + that are symbolic links (a Unix filesystem feature) are excluded from the input. + \anchor cfg_exclude_patterns <dt>\c EXCLUDE_PATTERNS <dd> \addindex EXCLUDE_PATTERNS @@ -1168,6 +1179,13 @@ TAGFILES = file1=loc1 "file2 = loc2" ... </pre> in the class index. If set to \c NO only the inherited external classes will be listed. +\anchor cfg_external_groups +<dt>\c EXTERNAL_GROUPS <dd> + \addindex EXTERNAL_GROUPS + If the \c EXTERNAL_GROUPS tag is set to \c YES all external groups will be listed + in the modules index. If set to \c NO, only the current project's groups will + be listed. + \anchor cfg_perl_path <dt>\c PERL_PATH <dd> \addindex PERL_PATH diff --git a/doc/install.doc b/doc/install.doc index f565ab1..49b3d9c 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -66,6 +66,9 @@ tools should be installed. \latexonly(see {\tt http://www.research.att.com/sw/tools/graphviz/})\endlatexonly. Needed for the include dependency graphs, the graphical inheritance graphs, and the collaboration graphs. + \note If you compile graphviz yourself, make sure you do include + freetype support (which requires the freetype library and header files), + otherwise dot will produce a warning that it cannot find doxfont! <li>The ghostscript interpreter. </ul> diff --git a/doc/language.doc b/doc/language.doc index 0815eea..2e9f518 100644 --- a/doc/language.doc +++ b/doc/language.doc @@ -60,7 +60,7 @@ when the translator was updated. <TD>Chinese</TD> <TD>Wei Liu<br>Wang Weihan</TD> <TD>liuwei@NOSPAM.asiainfo.com<br>wangweihan@NOSPAM.capinfo.com.cn</TD> - <TD>1.2.11</TD> + <TD>up-to-date</TD> </TR> <TR BGCOLOR="#ffffff"> <TD>Croatian</TD> @@ -213,7 +213,7 @@ when the translator was updated. \hline Brazilian & Fabio "FJTC" Jun Takada Chino & {\tt chino@icmc.sc.usp.br} & up-to-date \\ \hline - Chinese & Wei Liu & {\tt liuwei@asiainfo.com} & 1.2.11 \\ + Chinese & Wei Liu & {\tt liuwei@asiainfo.com} & up-to-date \\ & Wang Weihan & {\tt wangweihan@capinfo.com.cn} & \\ \hline Croatian & Boris Bralo & {\tt boris.bralo@zg.tel.hr} & up-to-date \\ @@ -527,10 +527,24 @@ translator adapter, that is used as your base class. When there is not such a method in your translator adapter base class, you probably can change the translator adapter base to the newer one. -Do not blindly implement all methods that are implemented by your -translator adapter base class. The reason is that the adapter +Probably the easiest approach of the gradual update is to look at +the translator report to the part where the list of the implemented +translator adapters is shown. Then: + - Look how many required methods each adapter implements and guess + how many methods you are willing to update (to spend the time + with). + - Choose the related oldest translator adapters to be removed (i.e. + not used by your translator). + - Change the base class of your translator class to the translator + adapter that you want to use. + - Implement the methods that were implemented by the older translator + adapters. + +Notice: Do not blindly implement all methods that are implemented by +your translator adapter base class. The reason is that the adapter classes implement also obsolete methods. Another reason is that -some of the methods could become obsolete from some newer adapter on. +some of the methods could become obsolete from some newer adapter +on. Focus on the methods listed as \e required. <b>The really obsolete language translators</b> may lead to too much complicated adapters. Because of that, doxygen developers may decide diff --git a/doc/language.tpl b/doc/language.tpl index d000bb6..bc14fd5 100644 --- a/doc/language.tpl +++ b/doc/language.tpl @@ -291,10 +291,24 @@ translator adapter, that is used as your base class. When there is not such a method in your translator adapter base class, you probably can change the translator adapter base to the newer one. -Do not blindly implement all methods that are implemented by your -translator adapter base class. The reason is that the adapter +Probably the easiest approach of the gradual update is to look at +the translator report to the part where the list of the implemented +translator adapters is shown. Then: + - Look how many required methods each adapter implements and guess + how many methods you are willing to update (to spend the time + with). + - Choose the related oldest translator adapters to be removed (i.e. + not used by your translator). + - Change the base class of your translator class to the translator + adapter that you want to use. + - Implement the methods that were implemented by the older translator + adapters. + +Notice: Do not blindly implement all methods that are implemented by +your translator adapter base class. The reason is that the adapter classes implement also obsolete methods. Another reason is that -some of the methods could become obsolete from some newer adapter on. +some of the methods could become obsolete from some newer adapter +on. Focus on the methods listed as \e required. <b>The really obsolete language translators</b> may lead to too much complicated adapters. Because of that, doxygen developers may decide diff --git a/doc/translator.pl b/doc/translator.pl index 1bba346..5efecc0 100644 --- a/doc/translator.pl +++ b/doc/translator.pl @@ -95,6 +95,21 @@ # as "obsolete" in the status (i.e. no guessing when it was last updated). # The translator report include the notice about that situation. # +# 2002/01/03 +# - Minor correction of regexp to obtain the list of translator_xx.h files. +# - Translator report ASCII file now lists the implemented translator +# adapter classes; so you can check how many steps behind the up-to-date +# status your translator is. +# +# 2002/01/07 +# - The list of the implemented translator-adapter classes now shows +# how many and what required methods the translator adapter implements. +# +# 2002/01/08 +# - The mistake in comments inside the translator report corrected. +# The older translator adapters are derived from newer ones. +# The mistaken comment said the opposite. +# ################################################################ use 5.005; @@ -193,7 +208,7 @@ sub GetPureVirtualFrom ##{{{ ################################################################ # StripArgIdentifiers takes a method prototype (one line string), # removes the argument identifiers, and returns only the necessary -# form of the prototype. +# form of the prototype as the function result. # sub StripArgIdentifiers ##{{{ { @@ -234,7 +249,7 @@ sub StripArgIdentifiers ##{{{ # Whitespaces are not only spaces. Moreover, the difference # may be in number of them in a sequence or in the type # of a whitespace. This is the reason to replace each sequence - # of whitespace by a single, real space. + # of whitespaces by a single, real space. # $arg =~ s{\s+}{ }g; @@ -346,6 +361,149 @@ sub GetInfoFrom ##{{{ ################################################################ +# GetAdapterClassesInfo returns the list of strings with information +# related to the adapter classes. Each one-line string contains the +# identifier of the adapter class and the number of required methods +# that are implemented by the adapter. +# +# The function takes one agument -- the reference to the hash with +# stripped prototypes of the required methods. +# +sub GetAdapterClassesInfo ##{{{ +{ + # Get the reference to the hash with required prototypes. + # + my $reqref = shift; + + # Let's open the file with the translator adapter classes. + # + my $fin = "$srcdir/translator_adapter.h"; + open(FIN, "< $fin") or die "\nError when open < $fin: $!"; + my @content = <FIN>; + close FIN; + my $cont = join("", @content); + + # Prepare the list that will be returned as result. + # + my @result = (); + + # Remove the preprocessor directives. + # + $cont =~ s{^\s*#\w+.+$}{}mg; + + # Remove comments and empty lines. + # + $cont =~ s{\s*//.*$}{}mg; # remove one-line comments + $cont =~ s{/\*.+?\*/}{}sg; # remove C comments + $cont =~ s{\n\s*\n}{\n}sg; # remove empty lines + + # Place delimiters to separate the classes, and remove + # the TranslatorAdapterBase class. + # + $cont =~ s{\};\s*class\s+}{<class>}sg; + $cont =~ s{class\s+TranslatorAdapterBase\s+.+?<class>}{<class>}s; + $cont =~ s{\};}{}sg; + + # Remove the base classes and the beginning of the the class + # definitions. + # + $cont =~ s{(TranslatorAdapter[_0-9]+)\s*:.+?\{\s*(public\s*:)?}{$1}sg; + + # Remove all bodies of methods; + # + while ($cont =~ s/{[^{}]+?}//sg) {} + + # Remove the "virtual" keywords. + # + $cont =~ s{^\s*virtual\s+}{}mg; + + # Remove the empty lines. + # + $cont =~ s{\n\s*\n}{\n}sg; + + # Split the string into the lines again. + # + @content = split(/\n/, $cont); + + # Now the list contains only two kinds of lines. The first + # kind of lines starts with the <class> tag and contains the + # identifier of the class. The following lines list the + # non-stripped prototypes of implemented methods without the + # "virtual" keyword. + # + # Now we will produce the result by looping through all the + # lines and counting the prototypes of the required methods + # that are implemented by the adapter class. + # + my $info = ''; + my $cnt = 0; + my $methods = ''; + + foreach my $line (@content) + { + if ($line =~ m{^<class>(\w+)\s*$}i ) + { + # Another adapter class found. + # + my $adapter_class = $1; + + # If the $info is not empty then it contains partial + # information about the previously processed adapter. + # + if ($info ne '') + { + # Complete the $info and push it into the @result. + # + $info .= sprintf("\timplements %2d required method%s...\n", + $cnt, (($cnt != 1) ? 's' : '')); + $methods .= "\n"; + push(@result, "$info$methods"); + } + + # Initialize the counter and store the adapter class identifier + # in the $info. + # + $info = $adapter_class; + $cnt = 0; + $methods = ''; + } + else + { + # The line contains the prototype of the implemented method. + # If it is the required method, count it, and add it to the + # string of methods. + # + my $stripped_prototype = StripArgIdentifiers($line); + + if (defined $$reqref{$stripped_prototype}) + { + ++$cnt; + $methods .= " $line\n"; + } + } + } + + # If the $info is not empty then it contains partial + # information about the last processed adapter. + # + if ($info ne '') + { + # Complete the $info and push it into the @result. + # + $info .= sprintf("\timplements %2d required method%s...\n", + $cnt, (($cnt != 1) ? 's' : '')); + $methods .= "\n"; + push(@result, "$info$methods"); + } + + # Return the result list. + # + # push @result, $cont; # ??? + return @result; +} +##}}} + +################################################################ # GenerateLanguageDoc takes document templates and code sources # generates the content as expected in the $flangdoc file (the # part of the Doxygen documentation), and returns the result as a @@ -684,6 +842,7 @@ xxxTABLE_FOOTxxx } ##}}} + ################################################################ # CopyTemplateToLanguageDoc takes the $flangtpl template and # generates $flangdoc without using information from other @@ -816,7 +975,8 @@ print STDERR "\n\n"; closedir DIR; # ignore names with dot at the beginning my @files = sort - grep { -f "$srcdir/$_" && m{^translator_..\.h$}i } + grep { ! m{^translator_adapter\.h$}i } + grep { -f "$srcdir/$_" && m{^translator_\w+\.h$}i } @entries; ##}}} @@ -832,13 +992,15 @@ print STDERR "\n\n"; # my $output = ''; my %details = (); + + # Initialize the list of the required methods. + # + my %required = (); # Remove the argument identifiers from the method prototypes # to get only the required form of the prototype. Fill the # hash with them. #{{{ # - my %required = (); - foreach (@expected) { my $prototype = StripArgIdentifiers($_); $required{$prototype} = 1; @@ -1110,17 +1272,34 @@ print STDERR "\n\n"; } ##}}} + # List all the translator adapter classes to show for which versions + # the adapters had to be created. Show, how many and what new methods + # are implemented by the adapters. #{{{ + # + print FOUT "\n" .'-' x 70 . "\n"; + print FOUT <<'xxxENDxxx'; +The following translator adapter classes are implemented -- the older (with +lower number) are always derived from the newer. They implement the +listed required methods. Notice that some versions of doxygen did not +introduce any changes related to the language translators. From here you may +guess how much work should be done to update your translator: + +xxxENDxxx + + my @adapter_info = GetAdapterClassesInfo(\%required); + + foreach (@adapter_info) { print FOUT " $_"; } + + ##}}} # List the methods that are expected to be implemented. #{{{ # - print FOUT "\n\n" .'-' x 70 . "\n"; + print FOUT "\n" .'-' x 70 . "\n"; print FOUT "Localized translators are expected to implement " . "the following methods\n" . "(prototypes sorted aplhabetically):\n\n"; - foreach (sort @expected) { - print FOUT "$_\n"; - } + foreach (sort @expected) { print FOUT "$_\n"; } ##}}} # If there are some details for the translators, show them. #{{{ |