search

NOAA-EMC / WW3

WAVEWATCH III
Other
258 stars 514 forks source link

Doxygen copyright updates #842

Open MatthewMasarik-NOAA opened 1 year ago

MatthewMasarik-NOAA commented 1 year ago

Issue

Recently doxygen is being added to the code base for documentation. While a copyright statement exists in the current headers, the @copyright tag was only recently added as a requirement. Because of this some files have been doxygen-processed, but don't have the required @copyright block.

The files are:

Solution

This issue requests the files already marked with doxygen, but having no @copyright block, to have that added. Specifically, the following should be added to either the MODULE or PROGRAM block (see WW3/docs/ww3_doxy_tmpl.md) as appropriate:

!> @copyright Copyright 2009-2022 National Weather Service (NWS),
!>       National Oceanic and Atmospheric Administration.  All rights
!>       reserved.  WAVEWATCH III is a trademark of the NWS.
!>       No unauthorized use without permission.
ukmo-ccbunney commented 1 year ago

@MatthewMasarik-NOAA is there any way that the @copyright markup can reference a predefined "copyright string"? Sort of like a macro? That way, we could define the copyright text once somewhere central. It would also make updating the copyright easier. Just a thought...

MatthewMasarik-NOAA commented 1 year ago

@ukmo-ccbunney that's a really interesting idea. It would be great from a maintenance perspective as you point out. I'll give some thought on how that might be implemented. Thanks for the suggestion!

MatthewMasarik-NOAA commented 1 year ago

@ukmo-ccbunney from some initial thought I believe this is likely not feasible for the way we'd want it to function. I see it as two sub-problems, having the copyright statement in (1) the source, (2) the hosted doxygen html output. The second should be feasible by having a macro step anytime prior to generating the doxygen html output. I assume this should be easy to add in some manner by Github Actions/CI (though I don't know alot about these yet) on pushing. But now for the first, I don't see a way to do unfortunately. Given the source is publicly hosted, and needing to have the up-to-date copyright statement present anytime someone clones it, I think a macro step would have to occur just prior to every clone from github. I don't see a mechanism to handle that currently, but could be wrong.. happy to hear if other's have different ideas about this though

ukmo-ccbunney commented 1 year ago

@MatthewMasarik-NOAA Ah yes - I had overlooked the fact that the copyright needs to be explicitly present in the source code and not just the documentation. Silly me. Thanks for looking into it though!