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 | 23 | ||||
| -rw-r--r-- | doc/faq.doc | 11 | ||||
| -rw-r--r-- | doc/language.doc | 49 | ||||
| -rw-r--r-- | doc/language.tpl | 17 | ||||
| -rw-r--r-- | doc/maintainers.txt | 3 | ||||
| -rw-r--r-- | doc/translator.pl | 108 |
8 files changed, 182 insertions, 33 deletions
diff --git a/doc/Makefile.win_make.in b/doc/Makefile.win_make.in index 3161b31..7951ed8 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 /s /q /i ..\examples ..\html\examples + @xcopy /y /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 05820b0..bef074a 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 /s /q /i ..\examples ..\html\examples + @xcopy /y /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 b0fc9df..44c51b7 100644 --- a/doc/config.doc +++ b/doc/config.doc @@ -98,6 +98,7 @@ followed by the descriptions of the tags grouped by category. <li> \refitem cfg_ext_doc_paths EXT_DOC_PATHS <li> \refitem cfg_extra_packages EXTRA_PACKAGES <li> \refitem cfg_extract_all EXTRACT_ALL +<li> \refitem cfg_extract_local_classes EXTRACT_LOCAL_CLASSES <li> \refitem cfg_extract_private EXTRACT_PRIVATE <li> \refitem cfg_extract_static EXTRACT_STATIC <li> \refitem cfg_file_patterns FILE_PATTERNS @@ -132,6 +133,7 @@ followed by the descriptions of the tags grouped by category. <li> \refitem cfg_include_path INCLUDE_PATH <li> \refitem cfg_inherit_docs INHERIT_DOCS <li> \refitem cfg_inline_info INLINE_INFO +<li> \refitem cfg_inline_inherited_memb INLINE_INHERITED_MEMB <li> \refitem cfg_inline_sources INLINE_SOURCES <li> \refitem cfg_input INPUT <li> \refitem cfg_input_filter INPUT_FILTER @@ -228,8 +230,9 @@ followed by the descriptions of the tags grouped by category. documentation generated by doxygen is written. Doxygen will use this information to generate all constant output in the proper language. The default language is English, other supported languages are: - Dutch, French, Italian, Czech, Swedish, German, Finnish, Hungarian, Japanese, - Korean, Spanish, Russian, Croatian, Polish and Portuguese. + Brazilian, Chinese, Croatian, Czech, Danish, Dutch, Finnish, French, + German, Greek, Hungarian, Italian, Japanese, Korean, Norwegian, Polish, + Portuguese, Romanian, Russian, Slovak, Slovene, Spanish and Swedish. \anchor cfg_extract_all <dt>\c EXTRACT_ALL <dd> @@ -255,6 +258,14 @@ followed by the descriptions of the tags grouped by category. If the \c EXTRACT_STATIC tag is set to \c YES all static members of a file will be included in the documentation. +\anchor cfg_extract_local_classes +<dt>\c EXTRACT_LOCAL_CLASSES <dd> + \addindex EXTRACT_LOCAL_CLASSES + If the \c EXTRACT_LOCAL_CLASSES tag is set to \c YES classes (and structs) + defined locally in source files will be included in the documentation. + If set to NO only classes defined in header files are included. Does not + have any effect for Java sources. + \anchor cfg_hide_undoc_members <dt>\c HIDE_UNDOC_MEMBERS <dd> \addindex HIDE_UNDOC_MEMBERS @@ -299,6 +310,14 @@ followed by the descriptions of the tags grouped by category. doxygen will generate a detailed section even if there is only a brief description. +\anchor cfg_inline_inherited_memb +<dt>\c INLINE_INHERITED_MEMB <dd> +\addindex INLINE_INHERITED_MEMB + If the \c INLINE_INHERITED_MEMB tag is set to \c YES, doxygen will show all inherited + members of a class in the documentation of that class as if those members were + ordinary class members. Constructors, destructors and assignment operators of + the base classes will not be shown. + \anchor cfg_full_path_names <dt>\c FULL_PATH_NAMES <dd> \addindex FULL_PATH_NAMES diff --git a/doc/faq.doc b/doc/faq.doc index 1ed33dc..cf18fab 100644 --- a/doc/faq.doc +++ b/doc/faq.doc @@ -210,6 +210,17 @@ generator -> gen At the time I was looking into lex and yacc, where a lot of things start with "yy", so the "y" slipped in and made things pronouncable. +<li><b>What was the reason to develop doxygen?</b> + +I once wrote a GUI widget based on the Qt library (it is still available at +http://qdbttabular.sourceforge.net/ and maintained by Sven Meyer). +Qt had nicely generated documentation (using an internal tool which +they didn't want to release) and I wrote similar docs by hand. +This was a nightmare to maintain, so I wanted a similar tool. I looked at +Doc++ but that just wasn't good enough (it didn't support signals and +slots and did have the Qt look and feel I have grown to like), +so I started to write my own tool... + </ol> \htmlonly diff --git a/doc/language.doc b/doc/language.doc index 59e9e0c..bc1a145 100644 --- a/doc/language.doc +++ b/doc/language.doc @@ -25,13 +25,13 @@ Doxygen has built-in support for multiple languages. This means that the text fragments that doxygen generates can be produced in languages other than English (the default) at configuration time. -Currently (version 1.2.12-20011125), 24 languages +Currently (version 1.2.13), 25 languages are supported (sorted alphabetically): Brazilian Portuguese, Chinese, Croatian, Czech, Danish, Dutch, English, Finnish, French, German, -Hungarian, Italian, Japanese, Korean, Norwegian, -Polish, Portuguese, Romanian, Russian, Slovak, -Slovene, Spanish, Swedish, and Ukrainian. +Greek, Hungarian, Italian, Japanese, Korean, +Norwegian, Polish, Portuguese, Romanian, Russian, +Slovak, Slovene, Spanish, Swedish, and Ukrainian. The table of information related to the supported languages follows. It is sorted by language alphabetically. The <b>Status</b> column @@ -96,7 +96,7 @@ when the translator was updated. <TD>Finnish</TD> <TD>Olli Korhonen</TD> <TD>Olli.Korhonen@NOSPAM.ccc.fi</TD> - <TD>1.0.0</TD> + <TD>obsolete</TD> </TR> <TR BGCOLOR="#ffffff"> <TD>French</TD> @@ -111,6 +111,12 @@ when the translator was updated. <TD>up-to-date</TD> </TR> <TR BGCOLOR="#ffffff"> + <TD>Greek</TD> + <TD>Harry Kalogirou</TD> + <TD>harkal@NOSPAM.rainbow.cs.unipi.gr</TD> + <TD>1.2.11</TD> + </TR> + <TR BGCOLOR="#ffffff"> <TD>Hungarian</TD> <TD>Földvári György</TD> <TD>foldvari@NOSPAM.diatronltd.com</TD> @@ -118,8 +124,8 @@ when the translator was updated. </TR> <TR BGCOLOR="#ffffff"> <TD>Italian</TD> - <TD>Ahmed Aldo Faisal<br>Alessandro Falappa</TD> - <TD>aaf23@NOSPAM.cam.ac.uk<br>a.falappa@NOSPAM.flashnet.it</TD> + <TD>Alessandro Falappa<br>Ahmed Aldo Faisal</TD> + <TD>alessandro@NOSPAM.falappa.net<br>aaf23@NOSPAM.cam.ac.uk</TD> <TD>up-to-date</TD> </TR> <TR BGCOLOR="#ffffff"> @@ -186,7 +192,7 @@ when the translator was updated. <TD>Swedish</TD> <TD>XeT Erixon</TD> <TD>xet@NOSPAM.hem.passagen.se</TD> - <TD>1.0.0</TD> + <TD>obsolete</TD> </TR> <TR BGCOLOR="#ffffff"> <TD>Ukrainian</TD> @@ -220,17 +226,19 @@ when the translator was updated. \hline English & Dimitri van Heesch & {\tt dimitri@stack.nl} & up-to-date \\ \hline - Finnish & Olli Korhonen & {\tt Olli.Korhonen@ccc.fi} & 1.0.0 \\ + Finnish & Olli Korhonen & {\tt Olli.Korhonen@ccc.fi} & obsolete \\ \hline French & Xavier Outhier & {\tt xouthier@yahoo.fr} & up-to-date \\ \hline German & Jens Seidel & {\tt jensseidel@users.sf.net} & up-to-date \\ & Jens Breitenstein & {\tt Jens.Breitenstein@tlc.de} & \\ \hline + Greek & Harry Kalogirou & {\tt harkal@rainbow.cs.unipi.gr} & 1.2.11 \\ + \hline Hungarian & F\"{o}ldv\'{a}ri Gy\"{o}rgy & {\tt foldvari@diatronltd.com} & 1.2.1 \\ \hline - Italian & Ahmed Aldo Faisal & {\tt aaf23@cam.ac.uk} & up-to-date \\ - & Alessandro Falappa & {\tt a.falappa@flashnet.it} & \\ + Italian & Alessandro Falappa & {\tt alessandro@falappa.net} & up-to-date \\ + & Ahmed Aldo Faisal & {\tt aaf23@cam.ac.uk} & \\ \hline Japanese & Kenji Nagamatsu & {\tt naga@joyful.club.ne.jp} & 1.2.5 \\ \hline @@ -252,7 +260,7 @@ when the translator was updated. \hline Spanish & Francisco Oltra Thennet & {\tt foltra@puc.cl} & 1.2.7 \\ \hline - Swedish & XeT Erixon & {\tt xet@hem.passagen.se} & 1.0.0 \\ + Swedish & XeT Erixon & {\tt xet@hem.passagen.se} & obsolete \\ \hline Ukrainian & Olexij Tkatchenko & {\tt olexij.tkatchenko@gmx.de} & 1.2.11 \\ \hline @@ -523,5 +531,22 @@ 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. +<b>The really obsolete language translators</b> may lead to too much +complicated adapters. Because of that, doxygen developers may decide +to derive such translators from the \c TranslatorEnglish class, which +is by definition always up-to-date. + +When doing so, all the missing methods will be replaced by the +English translation. This means that not-implemented methods will +always return the English result. Such translators are marked using +word \c obsolete. You should read it <b>really obsolete</b>. No +guess about the last update can be done. + +Often, it is possible to construct better result from the obsolete +methods. Because of that, the translator adapter classes should be +used if possible. On the other hand, implementation of adapters for +really obsolete translators brings too much maintenance and +run-time overhead. + */ diff --git a/doc/language.tpl b/doc/language.tpl index 3982278..d000bb6 100644 --- a/doc/language.tpl +++ b/doc/language.tpl @@ -296,5 +296,22 @@ 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. +<b>The really obsolete language translators</b> may lead to too much +complicated adapters. Because of that, doxygen developers may decide +to derive such translators from the \c TranslatorEnglish class, which +is by definition always up-to-date. + +When doing so, all the missing methods will be replaced by the +English translation. This means that not-implemented methods will +always return the English result. Such translators are marked using +word \c obsolete. You should read it <b>really obsolete</b>. No +guess about the last update can be done. + +Often, it is possible to construct better result from the obsolete +methods. Because of that, the translator adapter classes should be +used if possible. On the other hand, implementation of adapters for +really obsolete translators brings too much maintenance and +run-time overhead. + */ diff --git a/doc/maintainers.txt b/doc/maintainers.txt index f4fc5a4..c3eb204 100644 --- a/doc/maintainers.txt +++ b/doc/maintainers.txt @@ -33,6 +33,9 @@ German Jens Seidel: jensseidel@users.sf.net Jens Breitenstein: Jens.Breitenstein@tlc.de +Greek +Harry Kalogirou: harkal@rainbow.cs.unipi.gr + Hungarian Földvári György: foldvari@diatronltd.com diff --git a/doc/translator.pl b/doc/translator.pl index 58477af..1bba346 100644 --- a/doc/translator.pl +++ b/doc/translator.pl @@ -87,6 +87,14 @@ # like "almost up-to-date" any more. The script was simplified # to reflect the changes. # +# 2001/11/26 +# - Information about version of doxygen added to the top +# of the translator report (the ASCII file). +# - TranslatorEnglish can be used to solve really obsolete translators +# to make adapter classes simpler. Such translators are marked +# as "obsolete" in the status (i.e. no guessing when it was last updated). +# The translator report include the notice about that situation. +# ################################################################ use 5.005; @@ -527,7 +535,12 @@ xxxTABLE_FOOTxxx {$1.$2.$3}x; } - if ($i == 0) { $status = '?'; } + if ($i == 0) { + $i = $status =~ s{^TranslatorEnglish$} + {obsolete}x; + } + + if ($i == 0) { $status = 'strange'; } ##}}} @@ -890,11 +903,15 @@ print STDERR "\n\n"; # Loop through the list of expected methods and collect # the missing (new) methods. Do this only when it derives # from Translator or TranslatorAdapter classes (i.e. ignore - # any unusual kind of TranslatorXxxx implementation). #{{{ + # any unusual kind of TranslatorXxxx implementation). + # Accept also deriving from TranslatorEnglish, that can + # be done by doxygen developers to solve problems with + # some really outdated translators. #{{{ # my @missing_methods = (); - if ($base =~ m/^Translator(Adapter.*)?$/) { + if ($base =~ m/^Translator(Adapter.*)?$/ + || $base =~ m/^TranslatorEnglish$/) { foreach my $method (@expected) { # Get the stripped version of the prototype. @@ -921,15 +938,34 @@ print STDERR "\n\n"; $output .= "\n\n\n"; $output .= $class . " ($base)\n" . '-' x length($class) . "\n"; - if ($base !~ m/^Translator(Adapter.*)?$/) { - $output .= "\nThis is the unusual implementation of the " - . "translator. Its class is derived\n" + if ($base =~ m/^TranslatorEnglish$/) { + $output .= "\nThis translator is implemented via deriving " + . "from the English translator.\n" + . "This should be done only in the case when " + . "the language maintainer\n" + . "or the doxygen " + . "developers need to update some really old-dated " + . "translator.\n" + . "Otherwise, deriving from " + . "the translator adapter classes should be used\n" + . "for obsolete translators. " + . "If you still want some texts to be in English\n" + . "copy the sources of the English translator.\n\n" + . "The obsolete and missing method lists (below) " + . "reflect what have to be done\n" + . "to derive " + . "directly from the Translator class " + . "(i.e. to reach up-to-date status).\n"; + } + elsif ($base !~ m/^Translator(Adapter.*)?$/) { + $output .= "\nThis is some unusual implementation of the " + . "translator class. It is derived\n" . "from the $base base class. The usual translator" . "class derives\n" . "or from the Translator class or from some " . "TranslatorAdapter_x_x_x classes.\n" . "Because of that, nothing can be guessed about " - . "missing methods.\n"; + . "missing or obsolete methods.\n"; } if (@missing_methods) { @@ -951,24 +987,34 @@ print STDERR "\n\n"; } - # Generate the textual output file. + # Generate the ASCII output file. # my $fout = "$docdir/$ftranslatortxt"; - # Open it first. + # Open it first, and output the version information. #{{{ # open(FOUT, "> $fout") or die "\nError when open > $fout: $!"; + print FOUT "(version $doxversion)\n\n"; + ##}}} + # List the supported languages. #{{{ # my @all_translators = keys %cb; print FOUT "Doxygen supports the following (" . @all_translators . ") languages (sorted alphabetically):\n\n"; - - foreach (sort grep { s/^Translator(\w+)\b.*$/$1/ } @all_translators) { - print FOUT " $_\n"; - } + + my @languages = sort + grep { s/^Translator(\w+)\b.*$/$1/ } + @all_translators; + + my $languages = join(", ", @languages); + $languages =~ s{((\w+,\s){5})}{$1\n}g; + $languages =~ s{Brazilian}{Brazilian Portuguese}; + $languages =~ s{(,\s+)(\w+)$}{$1and $2.}s; + + print FOUT "$languages\n"; ##}}} # If there are up-to-date translators, list them. #{{{ @@ -1019,11 +1065,35 @@ print STDERR "\n\n"; } ##}}} + # If there are translators derived from TranslatorEnglish, list them + # and name them as obsolete. #{{{ + # + @list = sort grep { $cb{$_} =~ m/^TranslatorEnglish$/ } keys %cb; + + if (@list) { + print FOUT "\n" .'-' x 70 . "\n"; + print FOUT "The following translator classes are implemented " + . "via deriving\n" + . "from the English translator. This should be done only " + . "in the case\n" + . "when the language maintainer or the doxygen " + . "developers need to update\n" + . "some really outdated translator. Otherwise, deriving " + . "from\n" + . "the translator adapter classes should be prefered " + . "for obsolete translators.\n" + . "See details below in the report.\n\n"; + + foreach (@list) { print FOUT " $_\t($cb{$_})\n"; } + } + ##}}} + # If there are other translators, list them. #{{{ # @list = sort grep { $cb{$_} !~ m/^Translator$/ } - grep { $cb{$_} !~ m/^TranslatorAdapter_/ } + grep { $cb{$_} !~ m/^TranslatorAdapter_/ } + grep { $cb{$_} !~ m/^TranslatorEnglish$/ } keys %cb; if (@list) { @@ -1031,12 +1101,16 @@ print STDERR "\n\n"; print FOUT "The following translator classes are somehow different\n" . "(sorted alphabetically). This means that they " . "do not derive from\n" - . "the Translator class, nor from some of the adapter classes.\n\n"; - + . "the Translator class, nor from some of the adapter " + . "classes,\n" + . "nor from the TranslatorEnglish. Nothing can be guessed " + . "about the methods.\n\n"; + foreach (@list) { print FOUT " $_\t($cb{$_})\n"; } } ##}}} + # List the methods that are expected to be implemented. #{{{ # print FOUT "\n\n" .'-' x 70 . "\n"; @@ -1059,7 +1133,7 @@ print STDERR "\n\n"; } ##}}} - # Close the output file + # Close the ASCII output file # close FOUT; |