Re: [Doxygen-develop] How to support a new language???

[Dimitri v. H. <di...@st...>]

Hi Enno,

On Fri, Jul 22, 2005 at 04:04:30PM +0200, Enno Bartels wrote:
> Hi 
> 
> I would like to kick off  to support a new 
> language in doxygen, like ADA (.adb, .ads)or Matlab (.pro)
> 
> So this it the way it should be done - is that right?!
> 
> 1. So the first thing is to write a new parser and
>     adapt the "Makefile.in"
>    1.1. src/adacode.h
>    1.2. src/adacode.l    ->   Makefile (flex)   ->   src/adacode.cpp     
>  
>    1.3. src/adascanner.h
>    1.4. src/adascanner.l    ->   Makefile (flex)   ->    src/adascanner.cpp
> 
>     OR for matlab
> 
>    1.1. src/matlabcode.h
>    1.2. src/matlabcode.l    ->   Makefile (flex)   ->   src/matlabcode.cpp     
>  
>    1.3. src/matlabscanner.h
>    1.4. src/matlabscanner.l    ->   Makefile (flex)   ->    src/matlabscanner.cpp

That's correct.

>    Question: 
>        a.) What does the "XXXscanner.l" and 
>             what the "XXXcode.l" program
>             module?

The scanner should scan the input files (they are fed to the scanner one
by one at the stage where doxygen says Parsing ....).

The scanner should build a tree of nodes of type Entry (the root of the
tree is provided by the caller, the scanner should just add children to
the root or other child nodes). 

Each entry represents a "thing" (class, variable, namespace, function, etc) 
which can be documented (along with the documentation if available) or 
just documentation (if the documentation contains structural commands 
like @class or @fn). 

The scanner should extract comment blocks and pass them to the comment scanner
(see commentscan.h). Furthermore, the scanner should fill in as much
information about a "thing" as possible, but at least the section field
and the name.

The code file should contains the source code scanner, which is presented
with strings representing the input files (if SOURCE_BROWSER is YES) 
but also with the contents of \code ... \endcode blocks.
It should do syntax highlighting and cross-referencing of the code 
with the documentation and can use the information stored in FileDef
for that (i.e. getSourceDefinition(lineNr) and getSourceMember(lineNr)).
For proper cross-referencing both scanner.l and code.l should keep 
track of the current line number.

> 
>        b.) What does they need for a start version? 

You mean what is the minimum? The code parser can just pass the file 
(provided as a string) through CodeOutputInterface::codify. 

The scanner should at least add some Entry nodes to the root node.

>        c.) 
> 
> 
> 2. Register the new parser to the right extension
>      File:  src/doxygen.cpp     Line: 7765
> 
>     2.1. Doxygen::parserManager->registerParser(".adb",new AdaLanguageScanner);
>     2.2. Doxygen::parserManager->registerParser(".ads",new AdaLanguageScanner);
> 
>     or with matlab:
> 
>     2.1. Doxygen::parserManager->registerParser("pro",new MatlabLanguageScanner);

Correct.

>  3. Write some test case of ada or Matlab code
>      3.1. First test with only a main
>      3.2. Second test with hello world
>      3.3. etc.
> 
> So is this the right way to do this ?

Yes, I believe so.

Regards,
  Dimitri