[petsc-dev] Documentation comment support

[Karl Rupp]

Hi Barry,

the 'shaky scripts' will mostly be required with a 'no touch' policy on 
existing sources, i.e. adjusting the comment blocks such that they are 
recognized by doxygen. I get your point regarding a doxygen dependency, 
yet a dependency for a documentation system is much more controllable 
than a runtime library which you need to get installed at the user's 
machine.

The Fortran stubs certainly need additional consideration, yet I propose 
to have a closer look at what Doxygen can deliver rather than turning it 
down upfront.

Best regards,
Karli


On 01/09/2013 12:06 AM, Barry Smith wrote:
>
>    If we really need to write a hierarchy of shaky scripts to use oxygen, then why not just write a hierarchy of shaky scripts (like we do now) and not use doxygen?
>
>     Doxygen is an ugly dependency unless it truly delivers some fantastic feature we cannot reproduce I think it should be avoided. So what is that fantastic feature?
>
>
>     Barry
>
>    Yes sowing is an ugly dependency but at least it is OUR dependency. And yes I have no problem with Matt rewriting all of sowing in python :-)
>
>
>
>
> On Jan 8, 2013, at 9:32 PM, Jed Brown <jedbrown at mcs.anl.gov> wrote:
>
>> On Tue, Jan 8, 2013 at 8:45 PM, Karl Rupp <rupp at mcs.anl.gov> wrote:
>> I was thinking of using an input filter, perhaps after creating an index.
>>
>> http://www.stack.nl/~dimitri/doxygen/manual/config.html#cfg_input_filter
>>
>> If a single filter is sufficient for all files, this is indeed the better option. Thanks.
>>
>> We get the file name in argv[1] so it can use the path to do different things. For example, examples/tests/ are treated differently from examples/tutorials/, which are different from library code.
>