contribution guide

[pschlatt1]

Suggestion to extend the contribution guide (CONTRIBUTE.md):

• add a tag doc/ for PR that mainly relate to documentation update.
• extend the code snippet to include how documentation should be added (doxygen, Fortran comments).
  Any comments?

[njansson]

Sounds good. I guess we need to decide on a documentation style as well. Now it's mostly the same, but there're some outliers. I guess the most important thing to decide is how to document method's arguments, either:

!> Method foo
subroutine foo(x)
  integer, intent(in) :: x !< Argument blah
end subroutine foo

or:

!> Method foo
!! @param x argument blah
subroutine foo(x)
  integer, intent(in) :: x
end subroutine foo

[timofeymukha]

This is a tough one... I'm not sure which I like more. The first one is nice in the sense that the doc is right where one sees the variable. But the line can get very long if the docstring is extensive...

[timofeymukha]

@pschlatt1 @njansson I feel leaning towards method 1, at least for classes. Reading a big class like mesh_t would be annoying with method 2.

[timofeymukha]

@njansson
Is it possible for Doxygen to do

!> Method foo
subroutine foo(x)
  !< Argument blah
  integer, intent(in) :: x
end subroutine foo

When we have a long argument or docstring, so that one line becomes too long?
We do that in some classes, and I think it looks good!

[njansson]

@njansson Is it possible for Doxygen to do

!> Method foo
subroutine foo(x)
  !< Argument blah
  integer, intent(in) :: x
end subroutine foo

When we have a long argument or docstring, so that one line becomes too long? We do that in some classes, and I think it looks good!

Don't think so, for the argument you would then have todo !> instead of !< (and put it above the documented entity)

[timofeymukha]

@njansson @pschlatt1 After having written a bit more documentation myself, I think that for subroutines the only option that can be universal is using @param and having everything on top of the definition. The inline option always has the risk of creating a huge line, which doesn't fit in the editor.

For classes, I think the current approach having the docstring above the attribute, like

  type, abstract, public :: time_scheme_t
     !> The coefficients of the scheme
     real(kind=rp), dimension(10) :: coeffs 
     !> Controls the actual order of the scheme, e.g. 1 at the first time-step
     integer :: n = 0
     !> Order of the scheme, defaults to 3
     integer :: time_order
     !> Device pointer for `coeffs`

Doxygen picks this up, and I guess one can do multiline as well