search

NOAA-EMC / WW3

WAVEWATCH III
Other
258 stars 521 forks source link

Add doxygen marked-down source #586

Open MatthewMasarik-NOAA opened 2 years ago

MatthewMasarik-NOAA commented 2 years ago

Add Doxygen Documentation

For each file, document each contained Fortran code units (file, module, subroutine, etc.) using the agreed upon doxygen headers:

ukmo-ccbunney commented 2 years ago

I'm happy to do the documentation for w3ounfmetamd.F90 and w3metamd.f90.

MatthewMasarik-NOAA commented 2 years ago

That would be awesome @ukmo-ccbunney . I'll put your username next to those two so folks know it's claimed.

done!

ukmo-ccbunney commented 2 years ago

Hi @MatthewMasarik-NOAA

I have started to add some doxygen markup to one of the F90 files and tried running doxygen, but I am having a few problems. Is there a minimum version of doxygen that is required?

On my Linux box I have version 1.8.5 but it segfaults when I run it. The last few lines of output are here:

Preprocessing /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3servmd.F90...
Prepassing fixed form of /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3servmd.F90
Parsing file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3servmd.F90...
********************************************************************
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3servmd.F90 line: 2072, state: 4
********************************************************************
Segmentation fault

On my HPC, I have version 1.5.6 which seems to run, but the documentation for my module does not get generated correctly. It picks up the markup for the file (@brief and @author, etc), but all the entries for the module are not picked up (@brief, @details, @param, etc).

Perhaps I am invoking it wrong? I am simply running doxygen docs/Doxyfile.in from the top level.

Ta!

MatthewMasarik-NOAA commented 2 years ago

Hi @ukmo-ccbunney , hmm, let me have a look. It normally goes off without a hitch, so I'll see if anything needs to be changed in the Doxygen.in. I'll post back momentarily..

MatthewMasarik-NOAA commented 2 years ago

@ukmo-ccbunney , try moving the Doxygen.in file up to the top level, then call doxygen Doxygen.in from there. I think that may solve it because I have the INPUT resource in the Doxygen.in set to model/src. I originally worked with repo in that structure, and transitioned the Doxygen.in file into docs/ during the PR.

Please let me know if that works or not.

MatthewMasarik-NOAA commented 2 years ago

Ps, @ukmo-ccbunney I checked version on a linux vm I have and it's 1.8.17. I would think your version would be fine. If you want to push the branch your working on, I could try running it on my end to see if its due to the markup added, or something else like the environment

ukmo-ccbunney commented 2 years ago

Hmm...same issue unfortunately (exactly the same error message on version 1.8.5 on my Linux box).

Like I say, it sort of works on the older version on my HPC, but my markup for the module is not appearing. Perhaps I am doing something wrong with the markup? I've pushed my changes up to a branch here:

https://github.com/ukmo-waves/WW3/tree/doc/ounfmeta

I've only added markup to the "file" (top level) and the "module" so far. Only the "file" markup is generating any documentation at the moment. If you can have a quick look then that would be great :)

UPDATE: So - I fixed one issue: I had the doxygen markup defined inside the module/subroutine rather than above it (d'oh). I can now produce a sensible looking html file on my HPC. However, it still segfaults on my linux box with the newer version of doxygen. If I remove all the other *.F90 files from the src directory and only have my single modified file in there, then it works fine. Perhaps I have a buggy version of doxygen? I will continue to update my files and you can try generating the documentation at you end perhaps to see if works ok for you?

UPDATE 2: So - I have got it to work with v.1.8.5 of doxygen, but to do so I had to remove the following files from my src directory as they were causing errors that resulted in a segfault:

src/w3profsmd.F90
src/w3servmd.F90
src/w3timemd.F90
src/w3triamd.F90
src/wmupdtmd.F90
MatthewMasarik-NOAA commented 2 years ago

@ukmo-ccbunney I'm having a look at the source right now, I'll give some feedback shortly

ukmo-ccbunney commented 2 years ago

@MatthewMasarik-NOAA Quick update - I have installed a new version of doxygen via Conda and it solves the issue I was having. I still get errors from some files, but it no longer segfaults.

MatthewMasarik-NOAA commented 2 years ago

Interesting.. that's good to note the version may be important as others start documenting. I'm working with w3ounfmetamd.F90 and getting some similar behavior -- it's not producing output for file & module. Strange. I'll have it sorted out shortly

ukmo-ccbunney commented 2 years ago

I have it working for me now - have you tried my most recent commits?

MatthewMasarik-NOAA commented 2 years ago

That's great! Oops, didn't have the most recent.. I'm glad to hear it's working.

Also in your markup you mentioned how to document the module variables. I need to see if I had it right to use the @param tags, I think you may actually use inline comments for each. I'm checking into that, I didn't know module variables needed to be documented until @edwardhartnett commented, possibly he will chime in. I'll report back on it

ukmo-ccbunney commented 2 years ago

Great - thanks @MatthewMasarik-NOAA .

On a related note - do we have a policy on whether we are ditching the "WAVEWATCH III" header boxes, i.e. these:

!/
!/                  +-----------------------------------+
!/                  | WAVEWATCH III           NOAA/NCEP |
!/                  |           C. Bunney               |
!/                  |                                   |
!/                  |                        FORTRAN 90 |
!/                  | Last update :         09-Nov-2020 |
!/                  +-----------------------------------+

I am hoping we can get rid of them, as they take a lot of space and are repeated for every module/subroutine/function.

Also, are we keeping the change log in the comments, or are we going to rely on Git's commit log for this?

@aliabdolali and @JessicaMeixner-NOAA - do you have any opinions on this?

JessicaMeixner-NOAA commented 2 years ago

For now the doxygen is just an addition and we're keeping the normal WW3 header and logs. I'd be open to changes though. I'm not a huge fan of the log personally but there are a few comments here/there that are valuable. I'd hope we could keep the important parts of the descriptions.

ukmo-ccbunney commented 2 years ago

For now the doxygen is just an addition and we're keeping the normal WW3 header and logs. I'd be open to changes though. I'm not a huge fan of the log personally but there are a few comments here/there that are valuable. I'd hope we could keep the important parts of the descriptions.

OK - I have deleted the sections that relate to the new Doxygen tags though (i.e. "1. Purpose", "2. Method", "3. Parameters", etc. I have left the header and the change log though. Should have I left the others untouched too?

MatthewMasarik-NOAA commented 2 years ago

I'd agree with @JessicaMeixner-NOAA , we had some discussions on this. I believe leaving the original headers intact (no markup) and adding some (relatively brief) doxygen markup above them is best. As you noted, the source below the tags is all displayed right below the marked up information.

MatthewMasarik-NOAA commented 2 years ago

OK - I have deleted the sections that relate to the new Doxygen tags though (i.e. "1. Purpose", "2. Method", "3. Parameters", etc. I have left the header and the change log though. Should have I left the others untouched too?

The approach I have been using is to leave the header completely untouched, then copy (or summarize in 1 sentence) the 1. Purpose content into the @brief tag. For the @details, I was putting a couple summarizing sentences from 2. Method, or elsewhere in the header that seemed helpful. I shoot for ~1 paragraph of info. I think there's roof for individual taste here though. Does that get at what you're asking?

MatthewMasarik-NOAA commented 2 years ago

*roof = room

ukmo-ccbunney commented 2 years ago

OK - I have deleted the sections that relate to the new Doxygen tags though (i.e. "1. Purpose", "2. Method", "3. Parameters", etc. I have left the header and the change log though. Should have I left the others untouched too?

The approach I have been using is to leave the header completely untouched, then copy (or summarize in 1 sentence) the 1. Purpose content into the @brief tag. For the @details, I was putting a couple summarizing sentences from 2. Method, or elsewhere in the header that seemed helpful. I shoot for ~1 paragraph of info. I think there's roof for individual taste here though. Does that get at what you're asking?

Yeah - that's cool and pretty much what I have done. I will reinstate the original comments.

However, if you agree, I will not keep the original comment for the module itself in w3ounfmetamd. It is a very long description of the module and I have moved it to the doxygen @details section to make use of the extra markup available there. Is that ok? I will reinstate all the comments from the subroutines/fcuntions.

MatthewMasarik-NOAA commented 2 years ago

That seems just fine to me. For people documenting their own code you should have some license to how you want it. If you're documenting a someone else's code, we may want to be judicious with what is removed. I think what you mentioned sounds good

MatthewMasarik-NOAA commented 2 years ago

To follow up regarding the module variable documentation, do use inline comments where the variables are declared, and not with a @param tag in the doxygen header. That's my error in the Reference. I'll make a PR to correct that. Below I copy/pasted a comment from a closed PR in which @edwardhartnett shows this:

The !< marker can be used when var documentation is short enough to fit on one line, but is not mandatory. Just as with other doxygen documentation blocks, the !> marker can be used, and the documentation placed before the variable.

It should be noted that all module and type variables need documentation. That is, each variable must be documented, none skipped (or you will get warnings).

Here's an example using the !< marker, where each element of documentation fits on one line:

module ip_grid_mod
  use ip_grid_descriptor_mod
  implicit none

  integer, public, parameter :: EQUID_CYLIND_GRID_ID_GRIB1 = 0 !< Integer grid number for equidistant cylindrical grid in grib1
  integer, public, parameter :: MERCATOR_GRID_ID_GRIB1 = 1 !< Integer grid number for Mercator grid in grib1
  integer, public, parameter :: LAMBERT_CONF_GRID_ID_GRIB1 = 3 !< Integer grid number for Lambert Conformal grid in grib1
  integer, public, parameter :: GAUSSIAN_GRID_ID_GRIB1 = 4 !< Integer grid number for Gaussian grid in grib1
  integer, public, parameter :: POLAR_STEREO_GRID_ID_GRIB1 = 5 !< Integer grid number for polar stereo grid in grib1
  integer, public, parameter :: ROT_EQUID_CYLIND_E_GRID_ID_GRIB1 = 203 !< Integer grid number for rotated equidistant cylindrical E-stagger grid
  integer, public, parameter :: ROT_EQUID_CYLIND_B_GRID_ID_GRIB1 = 205 !< Integer grid number for rotated equidistant cylindrical B-stagger grid

  integer, public, parameter :: EQUID_CYLIND_GRID_ID_GRIB2 = 0 !< Integer grid number for equidistant cylindrical grid in grib2
  integer, public, parameter :: ROT_EQUID_CYLIND_GRID_ID_GRIB2 = 1 !< Integer grid number for rotated equidistant cylindrical grid in grib2
  integer, public, parameter :: MERCATOR_GRID_ID_GRIB2 = 10 !< Integer grid number for Mercator grid in grib2
  integer, public, parameter :: POLAR_STEREO_GRID_ID_GRIB2 = 20 !< Integer grid number for polar stereo grid in grib2
  integer, public, parameter :: LAMBERT_CONF_GRID_ID_GRIB2 = 30 !< Integer grid number for Lambert conformal grid in grib2
  integer, public, parameter :: GAUSSIAN_GRID_ID_GRIB2 = 40 !< Integer grid number for Gaussian grid in grib2

Here's an example where more detail is required, and the documentation elements usually come before the variables:

  type gribfield
     integer :: version        !< GRIB edition number (currently 2).

     !>     Message Discipline (see [Code Table 0.0]
     !>    (https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table0-0.shtml)).
     integer :: discipline

     !>    Contains the entries in the Identification Section (Section
     !>    1).
     !>    - idsect(1) Identification of originating Centre
     !>    (see Common Code Table C-1) 7 US National Weather Service. ([Table 0]
     !>    (https://www.nco.ncep.noaa.gov/pmb/docs/on388/table0.html)).
     !>    - idsect(2) Identification of originating Sub-centre ([Table C]
     !>    (https://www.nco.ncep.noaa.gov/pmb/docs/on388/tablec.html)).
     !>    - idsect(3) GRIB Master Tables Version Number. ([Table 1.0]
     !>    (https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table1-0.shtml))
     !>    0 Experimental; 1 Initial operational version number
     !>    - idsect(4) GRIB Local Tables Version Number ([Table 1.1]
     !>    (https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table1-1.shtml)).
     !>     - 0 Local tables not used
     !>     - 0 1-254 Number of local tables version used
     !>    - idsect(5) Significance of Reference Time ([Table 1.2]
     !>    (https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table1-1.shtml)).
     !>     - 0 Analysis
     !>     - 1 Start of forecast
     !>     - 2 Verifying time of forecast
     !>     - 3 Observation time
     !>    - idsect(6) Year (4 digits)
     !>    - idsect(7) Month
     !>    - idsect(8) Day
     !>    - idsect(9) Hour
     !>    - idsect(10) Minute
     !>    - idsect(11) Second
     !>    - idsect(12) Production status of processed data (see [Table 1.3]
     !>    (https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table1-3.shtml))
     !>     - 0 Operational products
     !>     - 1 Operational test products
     !>     - 2 Research products
     !>     - 3 Re-analysis products
     !>    - idsect(13) Type of processed data ([Table 1.4]
     !>    (https://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table1-4.shtml))
     !>     - 0 Analysis products
     !>     - 1 Forecast products
     !>     - 2 Analysis and forecast products
     !>     - 3 Control forecast products
     !>     - 4 Perturbed forecast products
     !>     - 5 Control and perturbed forecast products
     !>     - 6 Processed satellite observations
     !>     - 7 Processed radar observations
     integer, pointer, dimension(:) :: idsect => null()

     !>    Number of elements in idsect (always 13).
     integer :: idsectlen

     !>    Pointer to character array containing contents
     !>    of Local Section 2, if included.
     character(len = 1), pointer, dimension(:) :: local => null()

     !>    Length of array local.
     integer :: locallen
ukmo-ccbunney commented 2 years ago

@MatthewMasarik-NOAA - Okey-dokey. This is just for the module variables, yes? The subroutines and functions still use @param?

MatthewMasarik-NOAA commented 2 years ago

Yes, exactly correct.

edwardhartnett commented 2 years ago

In general the doxygen version is significant. 1.8.5 is very old and should be upgraded.

The reason includes the fact that the Doxyfile changes from version to version - new items are added, and some are taken away. We rely on several settings that are in more recent doxygen versions, including WARN_AS_ERROR.

When we set up the doxygen build in the CI, it will be using the doxygen release associated with "ubuntu-latest" which, currently, is 1.8.17. Everyone using doxygen on their own machine should upgrade to 1.8.17. Do not upgrade to 1.9.x, because that is not what will be used in the CI. So 1.8.17 is the canonical version of doxygen at the moment.

In general, close versions of doxygen usually work, though sometimes with extra warnings. But the doxygen build must target a specific version, which is currently 1.8.17.

On NCEPLIBS we converted all old logs to tables in the doxygen, for example:

!> ### Program History Log
!> Date | Programmer | Comments
!> -----|------------|---------
!> 2000-05-09 | Stephen Gilbert | Initial development
!> 2003-09-02 | Stephen Gilbert | Added GDT 3.31 Albers Equal Area
!> 2007-04-24 | Boi Vuong | Added GDT 3.204 Curilinear Orthogonal Grids
!> 2008-05-29 | Boi Vuong | Added GDT 3.32768 Rotate Lat/Lon E-grid
!> 2010-05-10 | Boi Vuong | Added GDT 3.32769 Rotate Lat/Lon Non E-Stagger grid
!> 2013-08-06 | Boi Vuong | Added GDT 3.4,3.5,3.12,3.101,3.140

This yields an attractive output, and is compact in the code.

In NCEPLIBS we took out all other headers and documentation blocks, and this is the common practice with doxygen projects. The goal is to have only what is needed, and, as was mentioned above, having some boilerplate headers at the top of every file is not useful. (We also have our legal disclaimer at the bottom of every README.md file.)

If there is a desire to have some repeated text appear everywhere, that can be done in doxygen, as a page header or footer, or in some other ways. Doxygen also has special handling for copyright information, should you wish to use it. (That is, you can define a copyright block and include it wherever you like).

In general, the text you want to repeat in the output documentation does not have to be repeated in the code everywhere.

MatthewMasarik-NOAA commented 2 years ago

Hey all, if you have completed files to add, you can commit them to the draft PR I just opened: #600 .

ukmo-ccbunney commented 2 years ago

@edwardhartnett I like the change history table idea. I will use that for the top level change log in the module. However, we have change logs on each individual function/subroutine too. I think this is a bit over the top in the documentation, so I won't elevate those to doxygen comments.

ukmo-ccbunney commented 2 years ago

Hey all, if you have completed files to add, you can commit them to the draft PR I just opened: #600 .

@MatthewMasarik-NOAA I don't have write access to your branch, so can't add my changes. I've got some files ready to go in my https://github.com/ukmo-waves/WW3/tree/doc/ounfmeta branch; shall I raise my own PR for them?

I would like your (or @edwardhartnett 's) input on one issue I have had though (for which I have a workaround that doesn't make sense to me!) See the comment here: https://github.com/ukmo-waves/WW3/blob/d130d7170872c5798d1d779b63a1a216a48f139d/model/src/w3ounfmetamd.F90#L164-L168

aliabdolali commented 2 years ago

Hey all, if you have completed files to add, you can commit them to the draft PR I just opened: #600 .

@MatthewMasarik-NOAA I don't have write access to your branch, so can't add my changes. I've got some files ready to go in my https://github.com/ukmo-waves/WW3/tree/doc/ounfmeta branch; shall I raise my own PR for them?

I would like your (or @edwardhartnett 's) input on one issue I have had though (for which I have a workaround that doesn't make sense to me!) See the comment here: https://github.com/ukmo-waves/WW3/blob/d130d7170872c5798d1d779b63a1a216a48f139d/model/src/w3ounfmetamd.F90#L164-L168

Hi @ukmo-ccbunney you can either make the PR to Matt's branch or to EMC/develop.

ukmo-ccbunney commented 2 years ago

I don't seem to be able to raise a PR in @MatthewMasarik-NOAA 's fork - it does not show as a list of base repos when doing a new PR (oddly, I can see everyone else's forks...). Shall I just raise this in the NOAA repo?

JessicaMeixner-NOAA commented 2 years ago

@MatthewMasarik-NOAA is out for the weekend. You can either wait until Matt gets back on Monday and he can just pull your changes in (so weird it's not listed) or just make a PR to the NOAA repo.

ukmo-ccbunney commented 2 years ago

No worries - I'll wait for Matt and he can pull my changes in. Cheers.

edwardhartnett commented 2 years ago

I am looking at the code here:

https://github.com/ukmo-waves/WW3/blob/d130d7170872c5798d1d779b63a1a216a48f139d/model/src/w3ounfmetamd.F90#L164-L168

What I see is:

!!
!! TODO - I NEED THIS DOUBLE BANG COMMENT HERE OTHERWISE DOXYGEN
!!        THROWS AN ERROR FOR THIS FILE: "State 22(String)"
!!        WHY???!!
!!
!/ ------------------------------------------------------------------- /
      MODULE W3OUNFMETAMD
!/
!/    02-Nov-2020 : Creation                            ( version 7.12 )
!/    26-Jan-2021 : Added TP and alternative dir/mag    ( version 7.12 )
!/                  metadata for directional fields.
!/    16-Dec-2020 : Added user partition templates      ( version 7.12 )
!/                  and coordinate reference system.
!/                  Freeform meta data uses linked list.
!/    02-Feb-2021 : Improved partitioned parameter      ( version 7.12 )
!/                  template string implementation.
!/    22-Mar-2021 : Adds extra coupling fields          ( version 7.13 )
!/    02-Sep-2021 : Add coordinates attribute           ( version 7.12 )
!/
!/ ------------------------------------------------------------------- /
!/
      USE NETCDF
      USE CONSTANTS, ONLY: TPIINV

I don't know why doxygen throws that error (what version of doxygen are you using?)

I do know that all modules need doxygen documentation, so it seems that instead of:

!! TODO - I NEED THIS DOUBLE BANG COMMENT HERE OTHERWISE DOXYGEN
!!        THROWS AN ERROR FOR THIS FILE: "State 22(String)"
!!        WHY???!!

You should have the doxygen block associated with module W3OUNFMETAMD.

In terms of the history logs, I suggest that all of them should be converted.

You guys are still used to looking at the documentation in the code. Once you get a nice doxygen build up on the web, it will become the habit to read the documentation there (the hyperlinking of functions, for example, makes it easier). So I would transfer all documentation to the doxygen, instead of leaving some in the code and some in doxygen.

IMO either the documentation is worth having or not. If not, it should be removed. If worth keeping, it should be in the doxygen, where all programmers, internal and external, can easily find it, and where it can be presented in an attractive and useful way.

edwardhartnett commented 2 years ago

Something that was not mentioned in the doxygen templates in this project: automatic hyperlinking of functions. This is very useful. Here's an example (from https://noaa-emc.github.io/NCEPLIBS-g2/):

image

Note that the function/subroutine names gribcreate() and addlocal(), are hyperlinks. If clicked through, this will bring up the doxygen for these functions. This is very useful when reading the documentation.

To achieve this, all Fortran function/subroutine names must be in lower-case in the documentation, and followed with parens. For example, here is the markdown that produced the doxygen output shown above:

To start a new GRIB2 message, call subroutine gribcreate(). It encodes
Sections 0 and 1 at the beginning of the message. This routine must be
used to create each message.

Note that no special extra work is required - just use lower-case for all function/subroutine names in the documentation, and always include empty parens after the name, and then doxygen will know that's a function/subroutine, and will link the documentation.

So we can't have:

gribcreate
GRIBCREATE()
gribcreate(some parameters)
GribCreate()

or any other variations or new creative ways to write function names. Only gribcreate() will work to let doxygen know it should link to the documentation for that function.

ukmo-ccbunney commented 2 years ago

@edwardhartnett

I don't know why doxygen throws that error (what version of doxygen are you using?)

version 1.8.18 (that's the closest I could get via Conda to 1.8.17 that you recommended).

You should have the doxygen block associated with module W3OUNFMETAMD.

I do - but if I don't end the Doxygen block for the module with a line with two bangs on (!!) then it throws that error. I don't have the same issue with my other module (w3metamd) though. It's very strange behaviour!

IMO either the documentation is worth having or not. If not, it should be removed. If worth keeping, it should be in the doxygen, where all programmers, internal and external, can easily find it, and where it can be presented in an attractive and useful way.

I agree whole-heartedly with this statement.

ukmo-ccbunney commented 2 years ago

@edwardhartnett

Something that was not mentioned in the doxygen templates in this project: automatic hyperlinking of functions. This is very useful.

I did try to use this...

To achieve this, all Fortran function/subroutine names must be in lower-case in the documentation, and followed with parens. For example, here is the markdown that produced the doxygen output shown above:

...but it didn't work, probably for the reason you mention. I will try updating my Doxygen code to see if making them lowercase helps!

edwardhartnett commented 2 years ago

Try removing this:

!/ ------------------------------------------------------------------- /

We removed all these kinds of ascii formatting elements from our code. Once we get used to reading the documentation on-line, these extra lines have no value.

Perhaps having the comment between the doxygen documentation block, and the start of the module, is causing the problem.

JessicaMeixner-NOAA commented 2 years ago

programmers will still look at the code... so having clean looking code is still of value

ukmo-ccbunney commented 2 years ago

Try removing this:

!/ ------------------------------------------------------------------- /

We removed all these kinds of ascii formatting elements from our code. Once we get used to reading the documentation on-line, these extra lines have no value.

Perhaps having the comment between the doxygen documentation block, and the start of the module, is causing the problem.

I still have the same issue if I remove that comment line. Also - I have the same lines in w3metamd and they don't upset Doxygen there. I notice that lots of other modules (that do not have Doxygen markup yet) are throwing similar errors:

Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3gridmd.F90 line: 7005, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3iorsmd.F90 line: 1616, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3nmlshelmd.F90 line: 1555, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3oacpmd.F90 line: 1239, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3ounfmetamd.F90 line: 4049, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3profsmd.F90 line: 4680, state: 4(SubprogBody)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3sbs1md.F90 line: 625, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3sbt4md.F90 line: 582, state: 15(ArrayInitializer)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3servmd.F90 line: 2072, state: 4(SubprogBody)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3snl5md.F90 line: 839, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3timemd.F90 line: 2024, state: 4(SubprogBody)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3triamd.F90 line: 2971, state: 4(SubprogBody)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/w3wavemd.F90 line: 1733, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/wmscrpmd.F90 line: 1594, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/wmupdtmd.F90 line: 2954, state: 4(SubprogBody)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/ww3_bound.F90 line: 622, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/ww3_ounf.F90 line: 4076, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/ww3_ounp.F90 line: 5505, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/ww3_prep.F90 line: 1742, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/ww3_prnc.F90 line: 2658, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/ww3_prtide.F90 line: 672, state: 22(String)
Error in file /net/data/users/frey/WW3Git/UKMO_WW3/model/src/ww3_trnc.F90 line: 1094, state: 22(String)
edwardhartnett commented 2 years ago

What is your branch and I will take a look.

ukmo-ccbunney commented 2 years ago

What is your branch and I will take a look.

Thanks @edwardhartnett This is the branch: https://github.com/ukmo-waves/WW3/tree/doc/ounfmeta I've added Doxygen comments to w3ounfmetamd.F90 (this is the one that causes issues without the double bang comment before the MODULE statement) and w3metamd.F90.

edwardhartnett commented 2 years ago

Since this branch does not seem to have the CMake build, how do you build the docs?

ukmo-ccbunney commented 2 years ago

I run doxygen docs/Doxyfile.in from the WW3 root directory. Is that wrong? 😬

Edit: This is branched from develop - not the cmake branch.

MatthewMasarik-NOAA commented 2 years ago

Hi @ukmo-ccbunney , I'm back from being away last week. I'm going to take quick look at your branch to see if something sticks out.. Do you have files to add to the PR I made?

Update: I'll pull in your doc/ounfmeta branch.

MatthewMasarik-NOAA commented 2 years ago

@ukmo-ccbunney I found how to fix the state: 22(String) error you we're getting. It wasn't anything you we're doing wrong, it was a setting in Doxygen.in for the EXTENSION_MAPPING. The default is empty. Here's the comment block with the Fortran specific entries added:

# Doxygen selects the parser to use depending on the extension of the files it 
# parses. With this tag you can assign which parser to use for a given 
# extension. Doxygen has a built-in mapping, but you can override or extend it
# using this tag. The format is ext=language, where ext is a file extension, and
# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, 
# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, 
# Fortran (fixed format Fortran: FortranFixed, free formatted Fortran:  
# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser 
# tries to guess whether the code is fixed or free formatted code, this is the 
# default for Fortran type files), VHDL, tcl. For instance to make doxygen treat 
# .inc files as Fortran files (default is PHP), and .f files as C (default is  
# Fortran), use: inc=Fortran f=C.                              
#                                             
# Note: For files without extension you can use no_extension as a placeholder.  
#                                                        
# Note that for custom extensions you also need to set FILE_PATTERNS otherwise   
# the files are not read by doxygen.     

EXTENSION_MAPPING      = f=FortranFixed f90=FortranFree F90=FortranFree

I'll PR this change.

edwardhartnett commented 2 years ago

@MatthewMasarik-NOAA I am so glad you found that, I was totally on the wrong track with this one! ;-)

And I should have remembered this because it came up in another project. by default .f90 is accepted as free-format Fortran, but not .F90!

ukmo-ccbunney commented 2 years ago

Hi @ukmo-ccbunney , I'm back from being away last week. I'm going to take quick look at your branch to see if something sticks out.. Do you have files to add to the PR I made?

Update: I'll pull in your doc/ounfmeta branch.

Thanks @MatthewMasarik-NOAA I've just pushed one small change to remove the comment line from w3ounfmetamd.F90.

BTW - I tried to raise a PR to target your branch, but your WW3 repo doesn't appear in the list of available target forks...which is odd. If you're happy to pull in my changes, then that's great.

MatthewMasarik-NOAA commented 2 years ago

BTW - I tried to raise a PR to target your branch, but your WW3 repo doesn't appear in the list of available target forks...which is odd. If you're happy to pull in my changes, then that's great.

@ukmo-ccbunney It is odd, I'm working to get that rectified. I'll let you know it's fixed, in the time being I'm happy to pull in your changes.

ukmo-ccbunney commented 2 years ago

@MatthewMasarik-NOAA I'm happy to update w3partmd, w3psmcmd and w3smcomd if you want to put my name against those (I can't edit the original PR description)

MatthewMasarik-NOAA commented 2 years ago

@ukmo-ccbunney that would be great. I just added you as a collaborator to the repo. See if that solved the issue... if not, I'll put you down for those files.

ukmo-ccbunney commented 2 years ago

@ukmo-ccbunney that would be great. I just added you as a collaborator to the repo. See if that solved the issue... if not, I'll put you down for those files.

I can't edit your PR description, but I can now raise a PR against your repo (although I have not done so yet), so it does fix that issue. If you can update the description with my name against those files I will raise a PR when I am done. Thanks!