How to inline sourcecode with doxygen

Question

I wanted to document a Fortran module containing functions with doxygen.

My problem is, that I can't find a way to include the body of my functions in the documentation of the functions. There is only a link to the position, but not the actual source code.

At the moment, my source code looks e.g. like this:

!> @brief      Get a starting time.
!> @details    Get an object with time information.
!> @return     returns the time with high precision
FUNCTION get_start_time() RESULT(stime)
  TYPE (time) :: stime

  CALL SYSTEM_CLOCK(stime%count, stime%rate, stime%max)
END FUNCTION

My doxygen configuration (the SOURCES part) looks like this:

SOURCE_BROWSER         = YES
INLINE_SOURCES         = YES
STRIP_CODE_COMMENTS    = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
REFERENCES_LINK_SOURCE = YES
SOURCE_TOOLTIPS        = YES
USE_HTAGS              = NO
VERBATIM_HEADERS       = YES

I also tried to use the @code and @endcode flags to mark the source, but this doesn't work, too.

What should I do, to get the source code directly to the documentation?

1st EDIT: I tried @cheeseminer's solution. So the code above now looks like

!> @brief      Get a starting time.
!> @details    Get an object with time information.
!> @return     returns the time with high precision
!> @par        Code
!> @snippet    folder/file.F90 get_start_time
!! [get_start_time]
FUNCTION get_start_time() RESULT(stime)
  TYPE (time) :: stime

  CALL SYSTEM_CLOCK(stime%count, stime%rate, stime%max)
END FUNCTION
!! [get_start_time]

Unfortunately, the block-id commands (those with !! in front) appear in the documentation and/or the full source code. What is the correct way, to do this in Fortran?

Or is there a better way to solve my initial question?

2nd EDIT: I found a workaround which hides the block-id. I wrapped them in an @internal command.

!> @internal [get_start_time]

3rd EDIT: I'm now using @Michael's suggestion to include the block-id as HTML-Comment.

!> <!-- [get_start_time] -->

4th EDIT: I posted a follow-up question concerning aliases.

I've not doxygenned Fortran myself, but looking at the manual don't you need to use !> for the snippet marker lines - at least, for the second one. It does not seem to make sense to need the @internal. — Cheeseminer
– Cheeseminer, Commented Jan 28, 2014 at 13:31
Removing @internal and using !> to get !> [get_start_time], I get the text "[get_start_time]" in the documentation (twice), which is not favourable. The @internal hides these occurrences. — Stefan
– Stefan, Commented Jan 28, 2014 at 14:15
Hmm, not favourable, I'd agree. I'm afraid I'm out of suggestions now. — Cheeseminer
– Cheeseminer, Commented Jan 28, 2014 at 14:22
don't use !>... just use a normal comment, doxygen will still find it — Michael
– Michael, Commented Jan 29, 2014 at 4:50
@Michael You are right that Doxygen will find it. But this way, the comments appear in the full source code listing, because they are not stripped by the option STRIP_CODE_COMMENTS. — Stefan
– Stefan, Commented Jan 29, 2014 at 5:08

albert · Accepted Answer · 2019-03-24 13:13:17Z

3

I think what you are looking for is @snippet. The relevant manual page is here. You'll need to provide a path to the 'example' code in the doxyfile too.

@code is more of a formatting command. If you have only a few short such sections you might be better to copy to code into the comment and use @code to format it, but if the code sample is liable to change then you probably should use snippet despite the clutter that it introduces into the source.

edited Mar 24, 2019 at 13:13

albert

9,2003 gold badges24 silver badges42 bronze badges

answered Jan 28, 2014 at 11:29

Cheeseminer

3,1281 gold badge24 silver badges38 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Stefan Over a year ago

Thanks for this first approach. Unfortunately, I have some problems with the block markers, which still appear either in the full source code, or the documentation part...

Collectives™ on Stack Overflow

How to inline sourcecode with doxygen

1 Answer 1

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related