[Developers] Documentation of output from tpl2cpp and tpl2rem

[Hans J. Skaug]

Hi John,

I did not think of actually letting Doxygen run tpl2cpp.
I am thinking about something simpler.

The basic problem I want to solve: the class "model_parameters"
is missing from the doxygen docs. The reason is that 
it is located in a *.htp file that is being generated by tpl2cpp.
"model_parameters" is an important class that should be documented.

Suggestion: we write an extensive tpl-file, say example.tpl, containing
all possible features of ADMB. Then we run "tpl2cpp example" manually.
We take the output (example.cpp and example.htp) and copy 
them manually over to the admb-trunk so that they get picked up by Doxygen.
They should not be part of the build though. We then document the two
files in the standard way, and suddenly Doxygen knows about
all the classes involved. This process is only done once, and if one in
the future adds new features to tpl2cpp, one needs to modify
example.cpp and example.htp manually accordingly.

If there is nothing wrong with the apprach I can take responsibility for
getting this started.

Hans

>
>Hi Hans,
>You suggestion to us Doxygen on some specific tpl interpreter or output
>would be feasible, not difficult, and generally illustrate what the tpl
>interpreters do for a few examples. But as you say, it would be very
>application-specific.
>
>You suggestion reminds me of a back-burner project I started a while
>back. Doxygen is capable of running a preprocessor on specified kinds of
>files and then processing the output. This capability is invoked by the
>FILTER_PATTERNS tag in the Doxyfile. There are some examples on the
>Doxygen website. I started writing a preprocessor for tpl translators
>using awk (FILTER_PATTERNS = *.tpl=tpl2dox). It was never very
>successful mainly because I wasn't clear in my own mind what I wanted it
>to do. Also, awk may not be the tool of choice; but it is a tool I
>understand. Your suggestion might help me clarify the goals of tpl2dox.
>Let me see if I can resurrect a working version to test out on some
>examples, but don't hold your breath.
>Cheers,
>John
>
>
>John Sibert
>Emeritus Researcher, SOEST
>University of Hawaii at Manoa
>
>Visit the ADMB project http://admb-project.org/
>
>On 12/10/2012 05:36 PM, Hans J. Skaug wrote:
>> Developers,
>>
>> The way I see it the classes and functions generated
>> by tpl2cpp and tpl2rem is not covered by Doxygen because
>> these resides in files that are project specific.
>> Nevertheless these classes are key to understanding
>> how ADMB works. What about the following idea:
>>
>> We include files generated by tpl2cpp:
>> example.cpp
>> example.htp
>> in the code base and document these such that they get
>> picked up by Doxygen.
>>
>> This could be a joint effort with many people contributing,
>> increasing our collective understanding of how things work.
>>
>> Hans
>> _______________________________________________
>> Developers mailing list
>> Developers at admb-project.org
>> http://lists.admb-project.org/mailman/listinfo/developers
>>