New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consistently document Fortran's equivalent function bodies (Origin: bugzilla #715172) #5360

Closed
doxygen opened this Issue Jul 2, 2018 · 0 comments

Comments

Projects
None yet
1 participant
@doxygen
Owner

doxygen commented Jul 2, 2018

status RESOLVED severity normal in component general for ---
Reported in version 1.8.5 on platform Other
Assigned to: Dimitri van Heesch

On 2013-11-25 15:46:19 +0000, Stefan wrote:

Hi there!

I just wanted to report that Doxygen is not consistently documenting equivalent function bodies in Fortran. As an example, have a look to that dummy code:

MODULE my_mod

CONTAINS

!> f1
ELEMENTAL INTEGER FUNCTION func1()
END FUNCTION

!> f2
ELEMENTAL FUNCTION func2()
INTEGER :: func2
END FUNCTION

!> f3
ELEMENTAL FUNCTION func3() RESULT(new)
INTEGER :: new
END FUNCTION

!> f4
INTEGER ELEMENTAL FUNCTION func4() RESULT(new)
END FUNCTION

END MODULE

PROGRAM main
USE my_mod

END PROGRAM
All four functions are doing the same. They are equivalent. The coding style is just a question of taste.
Doxygen, however, is documenting each differently. Not even capitalization is consistent. Would be awesome to fix this.

Cheers and all the very best,
Stefan

On 2013-12-01 10:06:21 +0000, albert wrote:

We have here a number of problems:

  • f2 not showing integer with function definition, this has been solved by bug_706804
  • inconsistency between upper and lower case, although controversial (see e.g. bug_695270, bug_712701) I pushed a solution to git (pull request 59) for consistency.
  • order of e.g. elemental and integer in equivalent function definitions (f1 and f4). I think we should not change this, it is the choice of the original software developer (the used coding standard) to write either elemental integer or integer elemental.

On 2013-12-07 22:30:12 +0000, Dimitri van Heesch wrote:

Thanks, I've just merged the pull request.

On 2013-12-19 15:36:30 +0000, Stefan wrote:

  • f2 not showing integer with function definition, this has been solved by
    bug_706804
    All right. The fix might make it into a future release. So far I am using Doxygen from trunk.
  • inconsistency between upper and lower case, although controversial (see e.g.
    bug_695270, bug_712701) I pushed a solution to git (pull request 59) for
    consistency.
    Right. For my point of view there are only two doable ways. Either change the case of all statements or leave it untouched as in the sources. The latter I prefer.
    Actually, the Fortran standard doesn't help much. It says in 1.4.5:
    Particular statements and attributes are identified in the text by an upper-case keyword, e.g., "END statement".
    For readability I am used to capitalize all keywords. However, this is just a question of taste. With C bindings, changing cases in Fortran code may become a real issue.

Thank you very much for your fix! It is pleasing my eyes.

  • order of e.g. elemental and integer in equivalent function definitions (f1
    and f4). I think we should not change this, it is the choice of the original
    software developer (the used coding standard) to write either elemental integer
    or integer elemental.
    Agreed.

On 2013-12-24 18:59:38 +0000, Dimitri van Heesch wrote:

This bug was previously marked ASSIGNED, which means it should be fixed in
doxygen version 1.8.6. Please verify if this is indeed the case. Reopen the
bug if you think it is not fixed and please include any additional information
that you think can be relevant (preferrably in the form of a self-contained example).

@doxygen doxygen closed this Jul 2, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment