doxygen-users — List for users of doxygen

Re: [Doxygen-users] Additional underscore character added in links to included files 1.8.12

[didje <dia...@pd...>]

I have added an example to the bug report.



--
View this message in context: http://doxygen.10944.n7.nabble.com/Additional-underscore-character-added-in-links-to-included-files-1-8-12-tp7734p7736.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

Re: [Doxygen-users] Additional underscore character added in links to included files 1.8.12

[Dimitri v. H. <do...@gm...>]

> On 18 Oct 2016, at 12:34 , didje <dia...@pd...> wrote:
> 
> Hi,
> 
> In 1.8.10, whenever there was a line as follows in a source file:
> include "folderA/fileX.h"
> the link was constructed as follows:
> href="../folderA/fileX_8h.html"
> 
> However, since I upgraded to 1.8.12, the link changes, and becomes:
> href="../folderA/fileX__8h.html"
> 
> An additional underscore is added before the "8h.html". 
> 
> As a result I have lots of broken links.

I haven't been able to reproduce this. So please create a self-contained
example (source + config file) that allows me to reproduce the problem and
attach that to a bug report filed here https://bugzilla.gnome.org/enter_bug.cgi?product=doxygen

Regards,
  Dimitri

[Doxygen-users] Additional underscore character added in links to included files 1.8.12

[didje <dia...@pd...>]

Hi,

In 1.8.10, whenever there was a line as follows in a source file:
include "folderA/fileX.h"
the link was constructed as follows:
href="../folderA/fileX_8h.html"

However, since I upgraded to 1.8.12, the link changes, and becomes:
href="../folderA/fileX__8h.html"

An additional underscore is added before the "8h.html". 

As a result I have lots of broken links.

It looks like a bug in Doxygen 1.8.12. If there is any way around it you can
suggest, I would greatly appreciate it, as I'd rather not go back to the
previous Doxygen version.

Thanks,



--
View this message in context: http://doxygen.10944.n7.nabble.com/Additional-underscore-character-added-in-links-to-included-files-1-8-12-tp7734.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

[Doxygen-users] Function Macros not documented

[ritwik.garg <gar...@gm...>]

I have some code of this sort:

header.h

    #define abc() xyz()

code.c

    #include "header.h"

    void xyz(){
        int a = 24;
    }

    void func_lmn(){
        abc();
    }

When I run doxygen on this code, the call graoh for function func_lmn() does
not contain either abc() or xyz(). Is it possble to do the same?

Following flags have been turned on:

ENABLE_PREPROCESSOR = YES
MACRO_EXPANSION = YES
SKIP_FUNCTION_MACROS = NO



--
View this message in context: http://doxygen.10944.n7.nabble.com/Function-Macros-not-documented-tp7733.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

Re: [Doxygen-users] Whither Fortran type-bound procedure documentation?

[Hambley, M. <mat...@me...>]

From: Albert [mailto:alb...@gm...]
> 
> Thank you for the example.
> 
> I see indeed a feature tthat is not supported yet in doxygen:
> generic,   public :: wibble => wibble_integer, wibble_real
> 
> It will take a it of time before I can have a good look at this
> problem.

While we would like a solution to these issues at some point, most of our code is written in Fortran 90 style so these problems don't arise. So we are happy to wait until it is convenient for you.

You don't explicitly address it so can you confirm that you understand the issue regarding the placement of argument documentation.

That type-bound procedures can be documented in the type declaration but not their arguments as they do not appear there. Meanwhile they can't be documented at the procedure definitions where the arguments do appear.

-- 
Matthew Hambley
  Scientific Software Engineer
  Met Office Hadley Centre, Exeter, UK

Re: [Doxygen-users] bug? - \snippet works, but not snippetlineno, snippetdoc ?

[Albert <alb...@gm...>]

Monique,

Have not read the email completely, but you wrote "In Doxygen 1.8.10, on
Windows 7, parsing .c code, the output for the \snippetlineno and
\snippetdoc commands seems broken.", these commands are new in doxygen
1.8.12 and there are also some changes in handling line numbers in a more
consistent way in the 1.8.12 version. Please have a look at the results for
the 1.8.12 version.

Albert

On Mon, Oct 3, 2016 at 9:45 PM, Monique Semp <mon...@ea...>
wrote:

> Hello, Doxygen users,
>
> *Short story:*
>
> In Doxygen 1.8.10, on Windows 7, parsing .c code, the output for the
> \snippetlineno and \snippetdoc commands seems broken. That is, the output
> does not match the content of the output for \snippet (which shows the
> expected code, proving that I do have correct file referencing). Similarly,
> the \include, \includelineno, and \includedoc output seems to be buggy,
> although not in the same way.
>
> I have my good-enough usage (using the \includelineno command), so I do
> not have an immediate question that needs an answer. This message is by way
> of info in case anyone wants to look into the issue further.
>
> ------------------
>
> *Details:*
>
> I’ve successfully set up an example file, snippet_one.inc, that uses “//!
> [snippet_name]” delimiters as the first and last lines of the file.
>
> I can include the snippet content (that’s between the delimiters) in
> multiple other file’s multiple other functions’ Doxygen comment output via
> the “\snippet    snippet_one.inc    snippet_name” command. So I know that
> I’ve correctly included the path in the EXAMPLE_PATH configuration, and
> that all relative paths are correctly working.
>
> * However, the output for the “\snippet” command appears with color syntax
> coding but no line numbers, contrary to how the \code samples appear (no
> color, but line numbered). I did not expect to see the line numbers (given
> the existence of the \snippetlineno command), but I didn’t expect or want
> the color syntax coding. (More about color coding for the \code command,
> below.)
>
> * When I tried the “\snippetlineno” command, the output changed to just a
> single line, “<file-name> <snippet_name>”; no code appeared. I didn’t
> change anything else except “snippet” –> “snippetlineno”.
>
> * I tried the “\snippetdoc” variant, and I got the same “<file-name>
> <snippet_name>” output.
>
> --
> (I also normally use the “@” form of doxygen commands instead of the “\”
> form, so I tried the “\” form for the snippetlineno and snippetdoc, but the
> results didn’t change.)
> --
>
> I figured I’d try the related “\include” and “\includelineno”, and
> “\includedoc” commands, and they also seem broken, but not the same way as
> the \snippet, \snippetlineno, \snippetdoc set.
>
> * The “\include” output (where I removed the “//! [snippet_name]”
> delimiters from the snippet_one.inc doc, and in the target file function
> block used just the filename without the <snippet_name>) was the same as
> the “\snippet” output: the code has color syntax coding but no line numbers.
>
> * The “\includelineno” output is the closest to what I’m looking for: it
> correctly includes the line numbers, but also still color codes things. (I
> don’t really care, but it is odd to see when the regular \code output isn’t
> color-coded.
>
> (I did find that if I explicitly set the language for the \code command,
> “\code {.c}”, I do not get the line numbers, but I do get color coding.
> Seems that someone figured this out about which formatters are used for
> which languages: http://stackoverflow.com/questions/21406101/doxygen-
> code-line-numbers.)
>
> * The “\includedoc” output doesn’t have the code, just the “<file-name>”
> string.
>
> --
> Other than the OPTIMIZE_OUTPUT_FOR_C = YES config option, I’m not sure if
> any other config options might be relevant?
>
> -Monique
>
>
> ------------------------------------------------------------
> ------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, SlashDot.org! http://sdm.link/slashdot
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>

[Doxygen-users] \code for .c code - output differs for .h/.c files

[Monique S. <mon...@ea...>]

So to add to the following comment from a related thread:

I did find that if I explicitly set the language for the \code command, “\code {.c}”, I do not get the line numbers, but I do get color coding. Seems that someone figured this out about which formatters are used for which languages: http://stackoverflow.com/questions/21406101/doxygen-code-line-numbers.)
And depending on whether I’m documenting a regular function (in a .c file) or a member function in a typedef struct (in a .h file), the \code command’s output is opposite with respect to line numbers and color-coding:
* In the .c file: With NO language qualifier, I get line numbers but no color-coding. WITH the {.c} qualifier, I get color coding but no line numbers.
* In the .h file: With NO language qualifier, I get color coding but no line numbers. WITH the {.unparsed} qualifier, I get line numbers but no color-coding. 
Other than the OPTIMIZE_OUTPUT_FOR_C = YES config option, I’m not sure if any other config options might be relevant?
So again, I can work with this, but I have to ask whether this is by design or a bug?
-Monique
 

[Doxygen-users] bug? - \snippet works, but not snippetlineno, snippetdoc ?

[Monique S. <mon...@ea...>]

Hello, Doxygen users,

Short story:

In Doxygen 1.8.10, on Windows 7, parsing .c code, the output for the \snippetlineno and \snippetdoc commands seems broken. That is, the output does not match the content of the output for \snippet (which shows the expected code, proving that I do have correct file referencing). Similarly, the \include, \includelineno, and \includedoc output seems to be buggy, although not in the same way.

I have my good-enough usage (using the \includelineno command), so I do not have an immediate question that needs an answer. This message is by way of info in case anyone wants to look into the issue further.

------------------

Details:

I’ve successfully set up an example file, snippet_one.inc, that uses “//! [snippet_name]” delimiters as the first and last lines of the file.

I can include the snippet content (that’s between the delimiters) in multiple other file’s multiple other functions’ Doxygen comment output via the “\snippet    snippet_one.inc    snippet_name” command. So I know that I’ve correctly included the path in the EXAMPLE_PATH configuration, and that all relative paths are correctly working.

* However, the output for the “\snippet” command appears with color syntax coding but no line numbers, contrary to how the \code samples appear (no color, but line numbered). I did not expect to see the line numbers (given the existence of the \snippetlineno command), but I didn’t expect or want the color syntax coding. (More about color coding for the \code command, below.)

* When I tried the “\snippetlineno” command, the output changed to just a single line, “<file-name> <snippet_name>”; no code appeared. I didn’t change anything else except “snippet” –> “snippetlineno”.

* I tried the “\snippetdoc” variant, and I got the same “<file-name> <snippet_name>” output.

--
(I also normally use the “@” form of doxygen commands instead of the “\” form, so I tried the “\” form for the snippetlineno and snippetdoc, but the results didn’t change.)
--

I figured I’d try the related “\include” and “\includelineno”, and “\includedoc” commands, and they also seem broken, but not the same way as the \snippet, \snippetlineno, \snippetdoc set.

* The “\include” output (where I removed the “//! [snippet_name]” delimiters from the snippet_one.inc doc, and in the target file function block used just the filename without the <snippet_name>) was the same as the “\snippet” output: the code has color syntax coding but no line numbers.

* The “\includelineno” output is the closest to what I’m looking for: it correctly includes the line numbers, but also still color codes things. (I don’t really care, but it is odd to see when the regular \code output isn’t color-coded.

(I did find that if I explicitly set the language for the \code command, “\code {.c}”, I do not get the line numbers, but I do get color coding. Seems that someone figured this out about which formatters are used for which languages: http://stackoverflow.com/questions/21406101/doxygen-code-line-numbers.)

* The “\includedoc” output doesn’t have the code, just the “<file-name>” string.

--
Other than the OPTIMIZE_OUTPUT_FOR_C = YES config option, I’m not sure if any other config options might be relevant?

-Monique

Re: [Doxygen-users] Match cpp and h file

[Fabian C. <Cen...@in...>]

>> I'm having a problem I don't understand. In a project with several
>> cpp and h files I have many classes that are fully documented.
>> There's also a cpp file with just global functions and a corresponding
>> h file. I have the full documentation for function parameters and
>> return type in the h file, in the cpp file is only a description. Somehow
>> doxygen (Win32 1.8.12) sees both parts but can't match the functions
>> up.
>> 
>> IBHelpers.cpp:65: warning: parameters of member GetIconIndex are not (all) documented
>> IBHelpers.cpp:65: warning: return type of member GetIconIndex is not documented
>> 
>> However in the generated documentation doxygen declares that the
>> same function is in both files.
>> 
>> GetIconIndex() : IBHelpers.h , IBHelpers.cpp
>> 
>> Why does doxygen see the global function in the h and cpp file but
>> can't combine the documentation for it? I don't have any problem
>> doing the same thing for classes and methods.
>
>This typically means that doxygen doesn't find a match between the parameters
>of the declaration and definition. So it considers them to be different functions
>(which could also happen in case of function overloading). 
>More details are needed to further analyse why this happens.

Thanks for the info. I copied the parameters from one file to the other
but that didn't help. I should also mention that I get this warning for
every function in these files, not just one. Here two examples:

--- .h ---
/*!
        \file
        ...
*/
/*!     \brief Get the index of the notebook page icon.
        \param apBookCtrl: Parent to get image list from.
        \return Index of image list icon for parent.
*/
int GetIconIndex(const wxBookCtrlBase* apBookCtrl);

/*!     \brief Check if program is registered for automatic startup.
        \param pszAppName: Name of key to check in registry.
        \param pszAppPath: Path of application that should be in the key.
        \return True if application is correctly registered for startup.
*/
BOOL IsProgramRegisteredForStartup(PCWSTR pszAppName, PCWSTR pszAppPath);

--- .cpp ---
/*!
        \file
        ...
*/
/*!     Get index of image list icon for the notebook control page.
*/
int GetIconIndex(const wxBookCtrlBase* apBookCtrl)

/*!     Check if program is registered for automatic startup.
*/
BOOL IsProgramRegisteredForStartup(PCWSTR pszAppName, PCWSTR pszAppPath)


So I get the warning for wx-types as well as "standard"
MSVC types. That's why I don't think it's something with
the functions declaration/documentation but rather something
either concerning the files as a whole or doxygen settings.
I only got the warnings at all after setting SHOW_FILES
to YES. I'd have imagined that doxygen would parse these
files and print warnings even if the files are not quoted
in the documentation.

Thanks

bye  Fabi

Re: [Doxygen-users] Match cpp and h file

[Dimitri v. H. <do...@gm...>]

> On 30 Sep 2016, at 16:50 , Fabian Cenedese <Cen...@in...> wrote:
> 
> Hi
> 
> I'm having a problem I don't understand. In a project with several
> cpp and h files I have many classes that are fully documented.
> There's also a cpp file with just global functions and a corresponding
> h file. I have the full documentation for function parameters and
> return type in the h file, in the cpp file is only a description. Somehow
> doxygen (Win32 1.8.12) sees both parts but can't match the functions
> up.
> 
> IBHelpers.cpp:65: warning: parameters of member GetIconIndex are not (all) documented
> IBHelpers.cpp:65: warning: return type of member GetIconIndex is not documented
> 
> However in the generated documentation doxygen declares that the
> same function is in both files.
> 
> GetIconIndex() : IBHelpers.h , IBHelpers.cpp
> 
> Why does doxygen see the global function in the h and cpp file but
> can't combine the documentation for it? I don't have any problem
> doing the same thing for classes and methods.

This typically means that doxygen doesn't find a match between the parameters
of the declaration and definition. So it considers them to be different functions
(which could also happen in case of function overloading). 
More details are needed to further analyse why this happens.

Regards,
  Dimitri

[Doxygen-users] Match cpp and h file

[Fabian C. <Cen...@in...>]

Hi

I'm having a problem I don't understand. In a project with several
cpp and h files I have many classes that are fully documented.
There's also a cpp file with just global functions and a corresponding
h file. I have the full documentation for function parameters and
return type in the h file, in the cpp file is only a description. Somehow
doxygen (Win32 1.8.12) sees both parts but can't match the functions
up.

IBHelpers.cpp:65: warning: parameters of member GetIconIndex are not (all) documented
IBHelpers.cpp:65: warning: return type of member GetIconIndex is not documented

However in the generated documentation doxygen declares that the
same function is in both files.

GetIconIndex() : IBHelpers.h , IBHelpers.cpp

Why does doxygen see the global function in the h and cpp file but
can't combine the documentation for it? I don't have any problem
doing the same thing for classes and methods.

Thanks

bye  Fabi

Re: [Doxygen-users] C++ 11/14, etc support

[Dimitri v. H. <do...@gm...>]

Hi Carey,

Doxygen should support all C++ features up to and including version 11.
C++14 doesn't have many new language changes that are relevant for doxygen's parser, so it should work as well.
C++17 has not been standardised, so it is not explicitly supported.

Regards,
  Dimitri

> On 22 Sep 2016, at 23:58 , CareyG <car...@ou...> wrote:
> 
> I can't find any documentation on the C++ 11/14/17 features supported by
> Doxygen versions.  Does such a document or web page exist?
> 
> I have code that is mostly written in older C++ (C++ x03) and an increasing
> amount written in C++ 11/14/17.  I need to know whether features such as
> final, template aliases, overrides, etc are supported as my developers
> increasingly use these features.  If they are not supported, I will have to
> find ways to work around the use of these language features.  And, if they
> are supported, I would like a reference document (or web page) that I can
> give to my developers.
> 
> Thanks,
> 
> Carey
> 
> 
> 
> --
> View this message in context: http://doxygen.10944.n7.nabble.com/C-11-14-etc-support-tp7717.html
> Sent from the Doxygen - Users mailing list archive at Nabble.com.
> 
> ------------------------------------------------------------------------------
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users

Re: [Doxygen-users] Using \includedoc with markdown

[Albert <alb...@gm...>]

Anas,

Please create a small test case and attach it to this  thread, so we can
see what can bee done.

Albert

On Fri, Sep 23, 2016 at 3:10 PM, Anas Nashif <na...@pl...> wrote:

> Hi,
> Yes, I tried, the contents of the markdown file are being included as
> (without line breaks), so there is no transformation.
>
> Anas
>
> On Fri, Sep 23, 2016 at 8:32 AM, Albert <alb...@gm...> wrote:
>
>> Anas,
>>
>> Did you try with a small test run? What was the result?
>>
>> Albert
>>
>> On Fri, Sep 23, 2016 at 1:22 PM, Anas Nashif <na...@pl...> wrote:
>>
>>> Hi,
>>> Is it possible to include markdown files and have them included for
>>> example to expand on the @details of a function?
>>>
>>> For example
>>>
>>> /**
>>>  * @brief This is an example
>>>  * @details
>>>  * @includedoc docs/example.md
>>>  * ..
>>>  */
>>>
>>> The contents of example.md would be parsed and included as formatted
>>> text.
>>>
>>> Or is there some other way to do this?
>>>
>>> Thanks,
>>> Anas
>>>
>>>
>>> ------------------------------------------------------------
>>> ------------------
>>>
>>> _______________________________________________
>>> Doxygen-users mailing list
>>> Dox...@li...
>>> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>>>
>>>
>>
>

Re: [Doxygen-users] Using \includedoc with markdown

[Anas N. <na...@pl...>]

Hi,
Yes, I tried, the contents of the markdown file are being included as
(without line breaks), so there is no transformation.

Anas

On Fri, Sep 23, 2016 at 8:32 AM, Albert <alb...@gm...> wrote:

> Anas,
>
> Did you try with a small test run? What was the result?
>
> Albert
>
> On Fri, Sep 23, 2016 at 1:22 PM, Anas Nashif <na...@pl...> wrote:
>
>> Hi,
>> Is it possible to include markdown files and have them included for
>> example to expand on the @details of a function?
>>
>> For example
>>
>> /**
>>  * @brief This is an example
>>  * @details
>>  * @includedoc docs/example.md
>>  * ..
>>  */
>>
>> The contents of example.md would be parsed and included as formatted
>> text.
>>
>> Or is there some other way to do this?
>>
>> Thanks,
>> Anas
>>
>>
>> ------------------------------------------------------------
>> ------------------
>>
>> _______________________________________________
>> Doxygen-users mailing list
>> Dox...@li...
>> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>>
>>
>

Re: [Doxygen-users] Using \includedoc with markdown

[Albert <alb...@gm...>]

Anas,

Did you try with a small test run? What was the result?

Albert

On Fri, Sep 23, 2016 at 1:22 PM, Anas Nashif <na...@pl...> wrote:

> Hi,
> Is it possible to include markdown files and have them included for
> example to expand on the @details of a function?
>
> For example
>
> /**
>  * @brief This is an example
>  * @details
>  * @includedoc docs/example.md
>  * ..
>  */
>
> The contents of example.md would be parsed and included as formatted text.
>
> Or is there some other way to do this?
>
> Thanks,
> Anas
>
>
> ------------------------------------------------------------
> ------------------
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>

[Doxygen-users] Using \includedoc with markdown

[Anas N. <na...@pl...>]

Hi,
Is it possible to include markdown files and have them included for example
to expand on the @details of a function?

For example

/**
 * @brief This is an example
 * @details
 * @includedoc docs/example.md
 * ..
 */

The contents of example.md would be parsed and included as formatted text.

Or is there some other way to do this?

Thanks,
Anas

Re: [Doxygen-users] C++ 11/14, etc support

[Andreas T. <an...@vi...>]

On 22.09.2016 23:58, CareyG wrote:

[snip]
> I have code that is mostly written in older C++ (C++ x03) and an increasing
> amount written in C++ 11/14/17.  I need to know whether features such as
> final, template aliases, overrides, etc are supported as my developers
> increasingly use these features.  If they are not supported, I will have to
> find ways to work around the use of these language features.  And, if they
> are supported, I would like a reference document (or web page) that I can
> give to my developers.

The latest version (1.8.12) of doxygen has a new option: 
CLANG_ASSISTED_PARSING. The documentation in the file says:

"# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the
# clang parser (see: http://clang.llvm.org/) for more accurate parsing 
at the
# cost of reduced performance. This can be particularly helpful with 
template
# rich C++ code for which doxygen's built-in parser lacks the necessary type
# information.
# Note: The availability of this option depends on whether or not 
doxygen was
# generated with the -Duse-libclang=ON option for CMake.
# The default value is: NO."

HTH and best regards
	Andreas
-- 
       ("`-''-/").___..--''"`-._
        `o_ o  )   `-.  (     ).`-.__.`)
        (_Y_.)'  ._   )  `._ `. ``-..-'
      _..`--'_..-_/  /--'_.' .'
     (il).-''  (li).'  ((!.-'

Andreas Tscharner   an...@vi...   ICQ-No. 14356454

[Doxygen-users] C++ 11/14, etc support

[CareyG <car...@ou...>]

I can't find any documentation on the C++ 11/14/17 features supported by
Doxygen versions.  Does such a document or web page exist?

I have code that is mostly written in older C++ (C++ x03) and an increasing
amount written in C++ 11/14/17.  I need to know whether features such as
final, template aliases, overrides, etc are supported as my developers
increasingly use these features.  If they are not supported, I will have to
find ways to work around the use of these language features.  And, if they
are supported, I would like a reference document (or web page) that I can
give to my developers.

Thanks,

Carey



--
View this message in context: http://doxygen.10944.n7.nabble.com/C-11-14-etc-support-tp7717.html
Sent from the Doxygen - Users mailing list archive at Nabble.com.

Re: [Doxygen-users] \warning - customize the "Warning" text ?

[Monique S. <mon...@ea...>]

Thanks, Luke!
I found that I needed to escape the quote marks that surround the class info, so the following result does exactly what I wish:
  ALIASES += memory{1}="<dl class=\"section memory\"><dt>Memory Usage</dt><dd>\1</dd></dl>"

And in my custom stylesheet (as assigned to the HTML_EXTRA_STYLESHEET config value in my Doxyfile), I simply added the dl.memory to the styling for dl.warning and dl.attention:

  dl.warning, dl.attention, dl.memory
  {
          margin-left:-7px;
          padding-left: 3px;
          border-left:4px solid;
          border-color: #FF0000;
  }

Thanks for the help!

-Monique

Re: [Doxygen-users] Whither Fortran type-bound procedure documentation?

[Albert <alb...@gm...>]

Matthew,

Thank you for the example.
I see indeed a feature tthat is not supported yet in doxygen:
generic,   public :: wibble => wibble_integer, wibble_real

It will take a it of time before I can have a good look at this problem.


Albert


On Thu, Sep 22, 2016 at 3:45 PM, Hambley, Matthew <
mat...@me...> wrote:

> From: Albert [mailto:alb...@gm...]
> >
> > Can you create a small  example to show the short comings?
>
> Of course. What follows is a Fortran module which should illustrate what I
> am trying to describe. (Object Fortran is, sadly, never short)
>
> Having carefully laid it out I suddenly had a nasty realisation that
> Outlook is probably about to mangle it horrible so I've attached a copy as
> well. Skip past the source code for commentary.
>
> module test_mod
>
>   use iso_fortran_env, only : output_unit
>
>   implicit none
>
>   private
>
>   !> @brief Type which does a thing
>   !> @details Documented where we would expect.
>   !>
>   type, public :: test_type
>
>     private
>
>     integer, allocatable :: foo(:)
>
>   contains
>
>     private
>     !> @brief Document in the type declaration
>     !> @details Not so good as there are no arguments here. If they are
>     !>          documented here they show up in documentation but Doxygen
>     !>          complains about them being documented but not existing. Of
>     !>          course they do, but further down.
>     !>
>     !>          Regardless the documentation is separate from the
>     !>          implementation.
>     !> @param teapot Some argument.
>     !>
>     procedure, public :: wobble
>     procedure, public :: wubble
>     generic,   public :: wibble => wibble_integer, wibble_real
>
>     !> @brief One aspect of wibble
>     !> @details I can document this here but it appears as a method of
>     !>          the type whereas really it should appear under
>     !>          "wibble". After all, it is private and not part of the
>     !>          API.
>     !>
>     procedure wibble_integer
>     procedure wibble_real
>
>     final :: destroy_test
>
>   end type test_type
>
>   interface test_type
>     procedure create_test_default
>     !> @brief Specific initialiser
>     !> @details Will this how up? No it will not.
>     procedure create_test_specific
>   end interface test_type
>
> contains
>
>   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
>   !> @brief Default initialiser
>   !>
>   !> @details It would be nice to document this here but it wont show up.
>   !>
>   function create_test_default() result(new_test)
>
>     implicit none
>
>     type(test_type) :: new_test
>
>     allocate( new_test%foo(10) )
>   end function create_test_default
>
> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
> function create_test_specific( tally ) result(new_test)
>
>     implicit none
>
>     integer, intent(in) :: tally
>
>     type(test_type) :: new_test
>
>     allocate( new_test%foo(tally) )
>
>   end function create_test_specific
>
>   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
> !!!!!!!!!!!!!
>   !> @brief Destructor.
>   !> @details Would prefer to document this here.
>   !>
>   subroutine destroy_test( this )
>
>     implicit none
>     type(test_type), intent(inout) :: this
>
>     deallocate( this%foo )
>
>   end subroutine destroy_test
>
>   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
> !!!!!!!!!!!!!
>   !> @brief A more sensible place to document.
>   !> @details But it does not appear.
>   !> @param teapot Some other argument.
>   !>
>   subroutine wobble( this, teapot )
>
>     implicit none
>
>     class(test_type), intent(in) :: this
>     integer,          intent(in) :: teapot
>
>     write( output_unit, '("wobble ", I0)' ) teapot
>
>   end subroutine wobble
>
>   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
> !!!!!!!!!!!!!
>   subroutine wubble( this, cheese )
>
>     implicit none
>
>     class(test_type), intent(in) :: this
>     integer,          intent(in) :: cheese
>
>     write( output_unit, '("wubble ", I0)' ) cheese
>
>   end subroutine wubble
>
>   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
> !!!!!!!!!!!!!
>   subroutine wibble_integer( this, value )
>
>     implicit none
>
>     class(test_type), intent(inout) :: this
>     integer,         intent(in) :: value
>
>     write( output_unit, '("wibble ", I0)' ) value
>
>   end subroutine wibble_integer
>
>   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
> !!!!!!!!!!!!!
>   !> @brief Again I would like to document this here.
>   !> @details But again it will not show up.
>   !> @param value A floating point argument.
>   !>
>   subroutine wibble_real( this, value )
>
>     implicit none
>
>     class(test_type), intent(inout) :: this
>     real,            intent(in) :: value
>
>     write( output_unit, '("wibble ", F14.4)' ) value
>
>   end subroutine wibble_real
>
> end module test_mod
>
> Running this through Doxygen I get the following messages:
>
> test_mod.f90:29: warning: Member wubble (function) of class
> test_mod::test_type is not documented.
>
> Of course it is, but at the definition rather than the declaration.
>
> test_mod.f90:30: warning: Member wibble=> wibble_integer, wibble_real
> (function) of class test_mod::test_type is not documented.
>
> This is sort of true except wibble is documented by wibble_integer and
> wibble_real.
>
> test_mod.f90:38: warning: Member wibble_real (function) of class
> test_mod::test_type is not documented.
>
> It is, but further down.
>
> test_mod.f90:40: warning: Member destroy_test (function) of class
> test_mod::test_type is not documented.
>
> Again, it is, but further down.
>
> test_mod.f90:13: warning: Member foo (variable) of class
> test_mod::test_type is not documented.
>
> True but irrelevant to the current issue.
>
> test_mod.f90:22: warning: argument 'teapot' of command @param is not found
> in the argument list of test_mod::test_type::wobble()
>
> It does, but at definition, not declaration.
>
> I realise that this is all pretty esoteric stuff and that there isn't a
> lot of object Fortran around but if you can suggest a solution I would be
> very grateful.
>

Re: [Doxygen-users] Whither Fortran type-bound procedure documentation?

[Hambley, M. <mat...@me...>]

From: Albert [mailto:alb...@gm...]
> 
> Can you create a small  example to show the short comings?

Of course. What follows is a Fortran module which should illustrate what I am trying to describe. (Object Fortran is, sadly, never short)

Having carefully laid it out I suddenly had a nasty realisation that Outlook is probably about to mangle it horrible so I've attached a copy as well. Skip past the source code for commentary.

module test_mod

  use iso_fortran_env, only : output_unit

  implicit none

  private

  !> @brief Type which does a thing
  !> @details Documented where we would expect.
  !>
  type, public :: test_type

    private

    integer, allocatable :: foo(:)

  contains

    private
    !> @brief Document in the type declaration
    !> @details Not so good as there are no arguments here. If they are
    !>          documented here they show up in documentation but Doxygen
    !>          complains about them being documented but not existing. Of
    !>          course they do, but further down.
    !>
    !>          Regardless the documentation is separate from the
    !>          implementation.
    !> @param teapot Some argument.
    !>
    procedure, public :: wobble
    procedure, public :: wubble
    generic,   public :: wibble => wibble_integer, wibble_real

    !> @brief One aspect of wibble
    !> @details I can document this here but it appears as a method of
    !>          the type whereas really it should appear under
    !>          "wibble". After all, it is private and not part of the
    !>          API.
    !>
    procedure wibble_integer
    procedure wibble_real

    final :: destroy_test

  end type test_type

  interface test_type
    procedure create_test_default
    !> @brief Specific initialiser
    !> @details Will this how up? No it will not.
    procedure create_test_specific
  end interface test_type

contains

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !> @brief Default initialiser
  !>
  !> @details It would be nice to document this here but it wont show up.
  !>
  function create_test_default() result(new_test)

    implicit none

    type(test_type) :: new_test

    allocate( new_test%foo(10) )
  end function create_test_default

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
function create_test_specific( tally ) result(new_test)

    implicit none

    integer, intent(in) :: tally

    type(test_type) :: new_test

    allocate( new_test%foo(tally) )

  end function create_test_specific

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !> @brief Destructor.
  !> @details Would prefer to document this here.
  !>
  subroutine destroy_test( this )

    implicit none
    type(test_type), intent(inout) :: this

    deallocate( this%foo )

  end subroutine destroy_test

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !> @brief A more sensible place to document.
  !> @details But it does not appear.
  !> @param teapot Some other argument.
  !>
  subroutine wobble( this, teapot )

    implicit none

    class(test_type), intent(in) :: this
    integer,          intent(in) :: teapot

    write( output_unit, '("wobble ", I0)' ) teapot

  end subroutine wobble

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  subroutine wubble( this, cheese )

    implicit none

    class(test_type), intent(in) :: this
    integer,          intent(in) :: cheese

    write( output_unit, '("wubble ", I0)' ) cheese

  end subroutine wubble

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  subroutine wibble_integer( this, value )

    implicit none

    class(test_type), intent(inout) :: this
    integer,         intent(in) :: value

    write( output_unit, '("wibble ", I0)' ) value

  end subroutine wibble_integer

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !> @brief Again I would like to document this here.
  !> @details But again it will not show up.
  !> @param value A floating point argument.
  !>
  subroutine wibble_real( this, value )

    implicit none

    class(test_type), intent(inout) :: this
    real,            intent(in) :: value

    write( output_unit, '("wibble ", F14.4)' ) value

  end subroutine wibble_real

end module test_mod

Running this through Doxygen I get the following messages:

test_mod.f90:29: warning: Member wubble (function) of class test_mod::test_type is not documented.

Of course it is, but at the definition rather than the declaration.

test_mod.f90:30: warning: Member wibble=> wibble_integer, wibble_real (function) of class test_mod::test_type is not documented.

This is sort of true except wibble is documented by wibble_integer and wibble_real.

test_mod.f90:38: warning: Member wibble_real (function) of class test_mod::test_type is not documented.

It is, but further down.

test_mod.f90:40: warning: Member destroy_test (function) of class test_mod::test_type is not documented.

Again, it is, but further down.

test_mod.f90:13: warning: Member foo (variable) of class test_mod::test_type is not documented.

True but irrelevant to the current issue.

test_mod.f90:22: warning: argument 'teapot' of command @param is not found in the argument list of test_mod::test_type::wobble()

It does, but at definition, not declaration.

I realise that this is all pretty esoteric stuff and that there isn't a lot of object Fortran around but if you can suggest a solution I would be very grateful.

Re: [Doxygen-users] \warning - customize the "Warning" text ?

[Lukas L. <l.l...@s-...>]

Hello Monique

I needed for my project something similar like you asked for. To achieve that I added a new alias

  tipp{1}=<dl class="section tipp"><dt>Tipp</dt><dd>\1</dd></dl>

and included a css file with the following in it:

dl.tipp

{

        margin-left: -7px;

        padding-left: 3px;

        border-left: 4px solid;

        border-color: #0000FF;

}

This produced the same as the warning command but with the text "Tipp" and the color blue.

Kind Regards

Lukas





Monique Semp wrote on 22.09.2016 at 01:02:

> Hello, Doxygen users,

>

> (Doxygen 1.8.10, Windows 7)

>

> Is there a way to create in essence an alias for the \warning command?

> I?m looking to create a ?Memory Usage? style for flagging memory

> issues, and it?d be ideal if I could simply change the ?Warning?

> label/text to say, ?Memory Usage?. (And bonus if I could change the

> red color to some other color.)

>

> One method is to use the \xrefitem and alias to customize the output

> text and styling, but I haven?t found a way to omit the consolidated

> page (the one that lists all the \xrefitem instances) from the output.

> And I don?t want a consolidated page of all ?memory usage? notes.

>

> Thanks,

> -Monique

Re: [Doxygen-users] Whither Fortran type-bound procedure documentation?

[Albert <alb...@gm...>]

Matthew,

Can you create a small  example to show the short comings?

Best Regards,

Albert

On Thu, Sep 22, 2016 at 11:25 AM, Hambley, Matthew <
mat...@me...> wrote:

> My original attempt to send this overtook my joining the mailing list so
> it is lost in limbo somewhere.
>
> Doxygen's approach to type-bound procedures in Fortran seems a little
> problematic. I've looked through my Doxyfile but can't see anything obvious
> which I should be changing but haven't.
>
> Let me elucidate:
>
> There are two places where one could put the documentation. Along with the
> declaration of the procedure, in the type definition. Alternatively it
> could go with the definition in the module body.
>
> Currently Doxygen seems to expect it to accompany declaration and ignores
> anything provided with definition.
>
> There are a number of issues with this.
>
> The calling signature of the procedure is not described in the declaration
> so Doxygen complains that you have @param clauses for non-existent
> arguments. Of course they do exist, just down in the definition.
>
> If you have a "generic" procedure, one which maps to a number of different
> implementations, i.e. overloaded, It can not be sensibly documented at
> declaration as there are multiple procedures but only one comment block.
>
> The upshot of all this is that the support for documentation seems to be
> in the wrong place. It would seem to make more sense for it to be with the
> procedure definition in the module body rather than in the module header in
> the type definition.
>
> Am I missing something? Is there already a way to get the behaviour I
> want? Or is this a shortcoming in the tool?
>
> --
> Matthew Hambley
>   Scientific Software Engineer
>   Met Office Hadley Centre, Exeter, UK
>
>
>
> ------------------------------------------------------------
> ------------------
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>

Re: [Doxygen-users] \warning - customize the "Warning" text ?

[Albert <alb...@gm...>]

Hello Monique,

Quite a few things in the doxygen HTML Pages can be steered with the css
file. Here you can steer the color of e.g. the warnings (items dl.warning,
dl.section). Splitting the warnings over categories is a different issue
that is currently only possible by means of \xref (as far as I know).

Best Regards,

Albert

On Thu, Sep 22, 2016 at 9:58 AM, Clemens Feige <c....@os...>
wrote:

> Monique Semp wrote on 22.09.2016 at 01:02:
> > Hello, Doxygen users,
> >
> > (Doxygen 1.8.10, Windows 7)
> >
> > Is there a way to create in essence an alias for the \warning command?
> > I’m looking to create a “Memory Usage” style for flagging memory issues,
> > and it’d be ideal if I could simply change the “Warning” label/text to
> > say, “Memory Usage”. (And bonus if I could change the red color to some
> > other color.)
> >
> > One method is to use the \xrefitem and alias to customize the output
> > text and styling, but I haven’t found a way to omit the consolidated
> > page (the one that lists all the \xrefitem instances) from the output.
> > And I don’t want a consolidated page of all “memory usage” notes.
> >
> > Thanks,
> > -Monique
>
> Hello Monique
>
>
> If you like to omit the auto-generated consolidated page (created by
> \xrefitem), then all you want seems to be a simple paragraph with
> headline "Memory Usage", do you?
>
> Then just make your own \memory (or @memory) command, as explained in
> the comments inside the configuration file:
>
> ALIAS = "memory=@par Memory Usage:\n"
>
>
> Clemens
>
> ------------------------------------------------------------
> ------------------
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>

[Doxygen-users] Whither Fortran type-bound procedure documentation?

[Hambley, M. <mat...@me...>]

My original attempt to send this overtook my joining the mailing list so it is lost in limbo somewhere.

Doxygen's approach to type-bound procedures in Fortran seems a little problematic. I've looked through my Doxyfile but can't see anything obvious which I should be changing but haven't.

Let me elucidate:

There are two places where one could put the documentation. Along with the declaration of the procedure, in the type definition. Alternatively it could go with the definition in the module body.

Currently Doxygen seems to expect it to accompany declaration and ignores anything provided with definition.

There are a number of issues with this.

The calling signature of the procedure is not described in the declaration so Doxygen complains that you have @param clauses for non-existent arguments. Of course they do exist, just down in the definition.

If you have a "generic" procedure, one which maps to a number of different implementations, i.e. overloaded, It can not be sensibly documented at declaration as there are multiple procedures but only one comment block.

The upshot of all this is that the support for documentation seems to be in the wrong place. It would seem to make more sense for it to be with the procedure definition in the module body rather than in the module header in the type definition.

Am I missing something? Is there already a way to get the behaviour I want? Or is this a shortcoming in the tool?

-- 
Matthew Hambley
  Scientific Software Engineer
  Met Office Hadley Centre, Exeter, UK