[Doxygen-develop] Canonical Names -- Was: Feature request

[Brendon C. <br...@ch...>]

Hi All,

I wrote a mail to this list a while ago describing a feature that I
would find very helpful in doxygen. I am willing to make the
modifications myself, however I dont know where to start looking in the
doxygen source base.

Basically i need to modify code that matches function names. I.e. I want
to update doxygen so that when processing it will consider the following
two function names to be the same:

Function(struct sockaddr const*)
Function(const sockaddr*)

That is just an example but the ordering of constness (In that example)
and a few other things like whether the user defines a "struct" keyword
make little difference. These still reference the same function. I need
this for a program i have written that will generate comments that can
be parsed by doxygen. The problem is that it generates in a sort of
"canonical" format, not necessarily the format that the user used in the
source, so doxygen fails to find functions referenced etc.

So could someone point me in the correct direction in the doxygen source
as to where i should be looking to modify this "matching" code?

By the way would the community be fine with including a patch that does
this? From my understanding it should have no effect on any existing
doxygen projects.

Thanks,
Brendon.



Brendon Costa wrote:
> Hi All,
> 
> (Feature request is at end of email if you are not interested in the
> reason why I request it).
> 
> 
> For a while I have been writing a tool that will allow C++ developers
> to generate documentation with a comprehensive list of exceptions that
> may propagate from any function. It does a number of other exception
> checks that check for dangerous/erroneous usage of exceptions.
> 
> Relevant to doxygen though, I am trying to get it to generate a file
> that can be processed by doxygen as a standard source file in order to
> add exception documentation to a functions doxygen documentation.
> 
> 
> It will currently generate a file with documentation for all functions
> that can throw exceptions in a format like:
> 
> /*! \fn Func(std::ostream&, addrinfo const*)
>  *
>  * Throws Exceptions:
>  *    - SysSocketException
>  *       - Originating from: GetAddress(sockaddr const*)
>  *          - E: OtherFunction(std::ostream&)
>  *          .
>  *       .
>  *
>  *    .
>  */
> 
> This file would be included by the doxygen parser along with all other
> source files and add the exception information to the functions
> existing documentation.
> 
> The amount of information generated is configurable, but as an example
> the above displays that the function: Func(std::ostream&, addrinfo
> const*) can throw a single exception of type: SysSocketException which
> was originally thrown in a function called GetAddress().
> 
> The E: OtherFunction() line is currently optional and tells the user
> that Func() makes a call to OtherFunction() which is the place where
> the exception may enter Func(). This allows users to identify where in
> the current function an exception will come from.
> 
> Now the problem is that I have a standard way of representing
> constness for function parameters. For example:
> GetAddress(sockaddr const*)
> 
> where in doxygen it is expecting whatever the user specified in the
> source file (Which can from what I understand may differ in terms of
> textual content but not semantics between the definition and
> implementation). So doxygen will fail to automatically create a link
> for a lot of my functions.
> 
> This becomes even more of a problem when as in the above example the
> function to which the documentation will belong is not identified so
> the \fn command is unable to find the function which this
> documentation block should belong.
> 
> 
> --- Feature Request --
> 
> Anyhow, as a feature request is it possible to request that doxygen be
> updated to recognise function parameters like: "sockaddr const*" to be
> the same as: "const sockaddr*"?
> 
> This feature could possibly be achieved with some simple text pattern
> matching. I would also request that it match regardless of whether the
> "struct" keyword is in the text also.
> 
> 
> Thanks,
> Brendon.
> 
> 
> 
>