include comment in subroutine/function hover

[michaelkonecny]

Often, we add comments above a function declaration to describe what it does, similarly to JavaDoc:

! This is an example subroutine. Call it whenever you want.
subroutine example()
   implicit none
end subroutine

Could this be included in the hover text?

Sometimes, there may be multiple lines, like this:

! generuje modifikaci deform pro prvek CBAR na zatizeni PLOAD1
!
! vstupy:
! x ... generovane rezy - reletivni souradnice
! p ... linie zatizeni [px1,py1, ... ,py2,pz2]
! l ... delka prvku
! st ... transformacni matice prvku z lokalu do globalu
! cc ... smykove konstanty
! A,Iy,Iz,It ... prurezove charakteristiky
!
! vystupy:
! u ... matice u(length(x),[ux uy uz rx ry rz]) v globalnim SS elementu
pure function CBarDeformPload1(x, p, S, cc, L, A, Iy, Iz, It, E, G) result(u)

(sorry for the Czech). In this case, I would only include the top N (N=10?) lines.

I've also seen people put the comment below the declaration:

subroutine example2()
! This is a description of what example2() does
    implicit none

although I'm not sure if this should be considered, it's not very common and personally, I would try to discourage it as it goes against patterns used in most other languages.

[hansec]

Thanks for the suggestion. I have thought about this, but haven't quite decide how useful it would be. In particular I see the following issues:

1. In my experience most Fortran subroutine documentation is quite long (for example BLAS/LAPACK) and providing a clipped view isn't particularly helpful.
2. Several code editors already provide an equivalent functionality through a popup view of the definition (ex. "code peek" in Visual Studio and VSCode).
3. There is no widely accepted documentation format for Fortran. Many codes use JavaDoc style comments before the object like you described, but many also use Python Docstring style comments inside the object. Additionally, many codes also have useless header, license or authorship information at the start of each doc comment.

I think the only way that documentation can really be supported by the language server is if there is some structure to it (or markup) that allows information to be extracted. This is how other language servers work, of course they have standardized documentation formats to work with. For Fortran, Doxygen is the only widely used documentation format, which I have considered adding support for.

I encourage others to chime in with their thoughts on this.

[PaulXiCao]

Personally, I found the FORD suite a lot better for Fortran documentation. It has structured documentation and one could (easily?) parse it.

[gnikit]

I think this should be marked as closed since docstrings have been supported for quite some time now (12/5/2019).