Can doxygen extract protection levels from itcl class members?

Question

I am trying to use doxygen to document my itcl code (version 1.8.2). However, it seems to miss the protection levels (public/protected/private). In addition, it lumps common variables in with instance variables, labelling all as static (only common should be static). Thirdly, it does not like constructors with initialization statments. All of these behaviors are evident from running doxygen on the code below. The first two behaviors are also evident from the tcl code example in the doxygen manual itself. Are these known limitations of the tcl scanner in doxygen? Thanks.

##\file

## MyClass
itcl::class MyClass {
    private common a     ;#< private common a
    protected common b   ;#< protected common b
    public common c      ;#< public common c
    private variable x   ;#< private variable x
    protected variable y ;#< protected variable y
    public variable z    ;#< public variable z
    ## private proc aa
    private proc aa args {}
    ## protected proc bb
    protected proc bb args {}
    ## public proc cc
    public proc cc args {}
    ## private method xx
    private method xx args {}
    ## protected method yy
    protected method yy args {}
    ## public method zz
    public method zz args {}
    ## constructor
    constructor args {} { 
        eval configure $args 
    }
}

Good question! No idea… – Donal Fellows Mar 05 '13 at 09:04 — Donal Fellows, Mar 05 '13 at 09:04

score 1 · Answer 1 · edited Dec 12 '18 at 10:34

There is a (practical) way to make doxygen aware of the scope of both class methods and instance and common variables. The generated doc still reports all ivars as "static", though.

The doxygen commands for determining the scope of a method/ivar are:

## \private
## \protected
## \public

I inferred this from the doxygen doc example, although the keywords exist as doxygen commands too.

There were a number of issues with doxygen and Tcl that I didn't manage to overcome.

instance variables are documented as "static"
Brief docs (;#< ) are not parsed for commands (such as \private, \protected), as your example also shown. I don't know if this is the expected behavior...
procs declared inside a class are ignored (though declaring them in any other namespace but the class' own works, even the parent namespace).

And there are no bugs reported in doxygen's bugzilla about this...

I've rewritten your example and added more examples of both what works and what doesn't.

##\file

## MyClass
itcl::class MyClass {

   ## \private common a
   private common a
   ## \protected common b
   protected common b 
   ## common c
   public common c

   private variable t   ;#<  variable x \private
   protected variable u ;#<  variable u \protected
   public variable v    ;#<  variable v \public

   private variable x   ;#< \private variable x 
   protected variable y ;#< \protected variable y
   public variable z    ;#< \public variable z

   ## \private proc aa
   private proc aa args {}
   ## \protected proc bb
   protected proc bb args {}

   private method xx args {} ;#< \private method xx
   protected method yy args {} ;#< \protected method yy
   public method zz args {} ;#< \public method zz


   ## \private variable k
   variable k   
   ## \protected variable l
   variable l
   ## \public variable m
   variable m   

   ## constructor
   constructor args {} { 
      eval configure $args 
   }

   ## proc proc comment
   proc cc { args } {}

}

## proc proc comment outside
proc dd { args } {}

namespace eval ::MyClass {
   ## proc proc comment outside
   proc ee { args } {}
}

Yes, I also tried using a pre-processor to insert the protection level commands, but gave up after the issue with procs inside classes. — Mark Armstrong, May 28 '13 at 16:05

Can doxygen extract protection levels from itcl class members?

1 Answers1