0

I found excellent information about introducing examples into my Doxygen output. Unfortunately, TCL scripts do not seem to work with the @examples command.

The examples page shows up but the entry for my included script has a horizontal rule where the example code should appear. (I can go into the Chrome developer's mode and confirm that the DIV tag pairs at this point have nothing between them.)

Interestingly, if I remove the extension from the filename in the @example command but keep the contents the same, I can see the code on the example page. There is something about Doxygen's processing of TCL code that is making this process fail.

I am hoping somebody else has experienced this and can tell me what I am doing wrong or confirm that Doxygen has trouble with TCL examples.

Command usage:

##@example csv-simple.tcl
# This example demonstrates creating the CSV object instance,
# loading data into it and finally serializing the data to an HTML doc.

csv-simple.tcl: (located in doc/examples folder)

package require ali

set mydata [ali::csv %AUTO% -header f]

$mydata setHeader [list A B C]
$mydata setData [list [list 1 2 3] [list 4 5 6] [list 7 8 9]]

$mydata writeFile "csv-simple.html" [$mydata serialize htmlDoc]

Doxyfile: The project path is {long path}/asl275 with folders doc/images, doc/examples and lib underneath.

OUTPUT_DIRECTORY = doc
ABBREVIATE_BRIEF = "The $name class" \
                     "The $name widget" \
                     "The $name file" \
                     is \
                     provides \
                     specifies \
                     contains \
                     represents \
                     a \
                     an \
                     the
FULL_PATH_NAMES = NO
JAVADOC_AUTOBRIEF = YES
TAB_SIZE = 3
TCL_SUBST = snit::type=itcl::class \
                     option=variable
TOC_INCLUDE_HEADINGS = 3
WARN_FORMAT = $file @ $line: $text
INPUT                  = doc/markdown \
                     lib
FILE_PATTERNS          = *.tcl \
                     *.vhd \
                     *.vhdl \
                     *.md
RECURSIVE = YES
EXCLUDE = lib/pkgIndex.tcl
EXAMPLE_PATH           = doc/examples
IMAGE_PATH             = doc/images
SOURCE_BROWSER         = YES
INLINE_SOURCE          = YES
GENERATE_TREEVIEW      = YES
GENERATE_LATEX         = NO
ENABLE_PREPROCESSING   = NO
CLASS_DIAGRAMS         = NO

The example path in the Doxygen configuration is setup properly to find the csv-simple.tcl and no error is reported when running the Doxygen GUI (v1.8.14).

Can anybody else reproduce my experience with TCL and Doxygen @examples?

FPGA-guy
  • 55
  • 6
  • Please include the image in the post as the link might not pe persistent. First guess is that it has to do with MARKDOWN processing, have a look in the doxygen configuration file (Doxyfile). Please specify which changes you already made to the Doxyfile. Also show the file cvs-simple.tcl – albert Feb 21 '18 at 08:57
  • Note that the csv-simple.tcl will display in the Doxygen generated examples when I remove the ".tcl" extension. – FPGA-guy Feb 21 '18 at 16:57
  • I can reproduce the problem given the above files and settings, strange as it doesn't really differs from the given cpp example in the documentation. Must be an problem in the example command. Similar problem with the include command. – albert Feb 21 '18 at 17:56
  • Thanks @albert for recreating this problem. I submitted [bug #793702](https://bugzilla.gnome.org/show_bug.cgi?id=793702) on bugzilla.gnome.org for Doxygen. – FPGA-guy Feb 21 '18 at 20:38
  • Thanks for the bug report, I added also the code to it. – albert Feb 22 '18 at 09:17
  • 1
    I've just pushed a proposed patch to github (pull request 662, https://github.com/doxygen/doxygen/pull/662). The problem with the include command was due to a typo in the include command in my test. – albert Feb 22 '18 at 18:46
  • In the mean time the pull request has been integrated in master on github. – albert Oct 21 '18 at 11:33

0 Answers0