You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The suggestion is to flesh out the Doxygen documentation (currently, almost no classes have documentation). I would suggest the following priorities:
A description of each class.
A document describing the overall object oriented class structure (this would be outside of Doxygen, maybe on the Wiki).
A description of each method. (Don't bother with methods that override an interface in a base class. This will help the user understand that this is just an implementation. But the description of the class SHOULD describe what is special about this implementation).
A description of each parameter for methods described in (3).
A description of local variables in the class (even private variables; that can be useful to understand how the class works)
The documentation should seek to clarify the following questions:
Which classes are interfaces vs. implementation? There is clearly an object oriented structure here, but it is not yet obvious.
Where is a method first defined (vs. being overridden)?
What steps must a user take if that user wishes to create a new version or kind \of a component? Which base class to use? What methods need to be implemented / overridden? How do other parts of PISM use this class?
For example of how these answers could be useful. Consider looking at PSGivenClimate. The following questions come up:
What does "S" mean in PSGivenClimate? What is PGivenClimate?
Why the complex templated set of base classes? What is the design here, and what is being accomplished?
Who uses PSGivenClimate? What base class do they see when using it?
This discussion was converted from issue #197 on December 02, 2021 21:39.
Heading
Bold
Italic
Quote
Code
Link
Numbered list
Unordered list
Task list
Attach files
Mention
Reference
Menu
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
The suggestion is to flesh out the Doxygen documentation (currently, almost no classes have documentation). I would suggest the following priorities:
The documentation should seek to clarify the following questions:
For example of how these answers could be useful. Consider looking at PSGivenClimate. The following questions come up:
Beta Was this translation helpful? Give feedback.
All reactions