[Developers] Documentation of output from tpl2cpp and tpl2rem

[John Sibert]

Hans,
I think your approach is reasonable and easily done.

The doxygen filter notion is a separate undertaking that I will chip 
away at seperately.

Thanks for taking this on.
John

John Sibert
Emeritus Researcher, SOEST
University of Hawaii at Manoa

Visit the ADMB project http://admb-project.org/

On 12/11/2012 12:11 PM, Hans J. Skaug wrote:
> 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
>>>
>