[petsc-dev] Documentation comment support

[Barry Smith]

On Jan 9, 2013, at 9:37 AM, Karl Rupp <rupp at mcs.anl.gov> wrote:

> 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.

   Our tar balls already have the fortran stubs and documentation built so for end users they need not install sowing. 

   Barry

    It is true that for people who use the repository directly sowing must be installed, but actually we've had very very few problems with sowing not being portable. The biggest problem with sowing is extending it is painful. It is not that sowing is badly designed it is just that it was written in haste so it is usually (always) not clear how to extend.


> 
> 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.
>> 
>