# sprint code_aster: configure doxygen to comment the source files

Issue #18 resolved
Mathieu Courtois created an issue

During the Code_Aster sprint 2 (see http://www.code-aster.org/wiki/doku.php?id=en:p03_dev:hackathon_02), a group worked on a configuration of doxygen to generate a documentation of the source code: fortran, python and headers.

• fortran: the comment must be placed before the subroutine they describe

• a template for fortran comments has been written with the description of the function, the parameters, formulas.

The html output was generated (1h10 on a laptop...).

To be tested: try doxygen > breathe > sphinx

!> Brief description of the subroutine,
!> continuation line
!>
!
!> Detailed description
!>
!> The lines must start with '!>' to be extracted by doxygen.
!>
!> Paragraphs are separated by a blank line.
!> Without blank line, the following lines are concatenated in the same paragraph.
!>
!> End of line may be inserted to start\n a new line.
!>
!> Equations can be inserted in the document using LaTeX syntax.
!>
!> Compute \f$\frac{d\lambda}{dt}, \frac{d\phi}{dt}, \frac{dz}{dt} \f$
!
!> @todo all todo comments will be visible in a single page.
!
!> @param[in]  neq      number of equations
!> @param[out] nnv      the output numbering
!
subroutine amdapt(neq, nbnd, nbsn, pe, nv,&
fctnzs, fctops, llist, nnv)
implicit none
...


1. reporter
• changed status to open

Hi, Maybe it is not the place to ask: do you know if the doxygen documentation will be made available somwhere on Code_Aster website or here? Thanks in advance for your reply. Bests, Pierre

2. reporter

Yes, it will but now there is a heavy work on the source files !

Thanks Mathieu for your quick reply. What is the plan? -> do you expect all the comments to be added by hand? -> or do you think a 1st step could be managed by a python script that would identify where is the copyright comments in each source file, and copy-paste the immediately following comment lines (that usually define the subroutine purposes) with the appropriate !> in beginning of lines?

Bests,

Pierre

3. reporter

Sure, by script first. Please open a new issue if you want to contribute.

Mathieu

Hi Mathieu, I will stay focus on SHB refactoring first (maybe till summer...). Then why not :). Bests, Pierre

Hi Mathieu,

A question: what kind of information should be written in the todo line?

I use to write "nothing identified" but I feel it's a quite useless information. I guess bitbucket tracking system is here already to keep track of the identified tasks yet to do.

May we simply remove this line?

Best regards,

Pierre

4. reporter

Hi,

Yes, keep this line only if you think this is something to fix or improve.

MC

Thanks Mathieu.

Last question: where should be positionned license related comments with respect to the doxygen documentation, before, after?

(the part that says:

! ====================================================================== ! COPYRIGHT (C) 1991 - 2012 EDF R&D WWW.CODE-ASTER.ORG ! THIS PROGRAM IS FREE SOFTWARE; YOU CAN REDISTRIBUTE IT AND/OR MODIFY ! IT UNDER THE TERMS OF THE GNU GENERAL PUBLIC LICENSE AS PUBLISHED BY ! THE FREE SOFTWARE FOUNDATION; EITHER VERSION 2 OF THE LICENSE, OR ! (AT YOUR OPTION) ANY LATER VERSION. ! ! THIS PROGRAM IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL, BUT ! WITHOUT ANY WARRANTY; WITHOUT EVEN THE IMPLIED WARRANTY OF ! MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. SEE THE GNU ! GENERAL PUBLIC LICENSE FOR MORE DETAILS. ! ! YOU SHOULD HAVE RECEIVED A COPY OF THE GNU GENERAL PUBLIC LICENSE ! ALONG WITH THIS PROGRAM; IF NOT, WRITE TO EDF R&D CODE_ASTER, ! 1 AVENUE DU GENERAL DE GAULLE, 92141 CLAMART CEDEX, FRANCE. ! ======================================================================

)

Should it be integrated in the doxygen documentation paragraph?