PMF class doco for developers

[HamishBrownPFR]

The view for each PMF class should display some infromation that is useful to developers and is in sync with the source code.

1. Some instructions that will guide developers but would not be included in science documentation
2. A list of the classes dependencies
3. A list of child functions that provide parameters to the class
4. These need to fit in with the current grid view for setting class properties.

1 could be achieved by picking up some kind of tag out of the source code and displaying it on the class view. Problem is the Science doco already uses the summary tag. Not sure of the solution here 2 could be done by making a list of Link not of type Function 3 could be done by making a list of Links of type Function and also displaying if they are optional or not.

[HamishBrownPFR]

This is now relevant to FunctionL

[sno036]

Can this be bumped up the priority list (along with all the other top-priority issues :-))?

From Hamish following him fixing one of my simulations: "Someone needs to write a class view for the UI that displays a list of the classes properties and parameters (including units) so you don’t have to go to the source code to work them out. There is an issue (# 480). I suggest posting something on this saying lack of doco is causing problems and this might spur some action in getting it working.

I think you may have inadvertently changed something in you SLURP model under replacements. I deleted this and ran the simulations again (which means it will use the XML in the resources file) and the N taken up numbers became sensible. This is the down side of using the replacements node to view the model, it makes accidental changes possible.

A solution to this would be if the SLURP node (or any crop for that matter) showed the tree view of its structure so users can look at the model and learn how it works but doesn’t allow setting of parameters. Not sure how feasible this is. In the meantime copy a fresh lot of The SLURP xml from the resources file and then comitt. Then if you are getting weird behaviour diff your .apsimx file and check there are not any unintended changes to the Slurp xml."

[HamishBrownPFR]

@hol353 This issue has always bugged me but the need for some better developer info on LifeCycle models has moved it up my priority list. I can have a go at implementing something here but not really sure how the views and presenters work.
Would I be able to have a chat with you at some stage to get some guidance on how best to approach this.

[hol353]

Happy to have a chat any time. If we can spec it up in sufficient detail then @hol430 could implement. The question is what do we want?

[HamishBrownPFR]

Some updated thoughts following discussion with @hol353 . Need to distinguish between two types of documentation.

1. Model documentation. This is the documentation that is generated into the .pdf model descriptions and displayed on the website. It describes how a model is configured using memos and class summary fields and documentation methods to construct the pdf.
2. User instructions. This is what is missing and what we are talking about here. It is to be generated and displayed on the view for each model in the GUI. It describes how to configure a model (as opposed to above which describes how the model is configured). Intent is to use Class remarks field and summary fields on class members to create this. A mock up of how this could look is provided in the figure.

Implementation notes.

• LifeCyclePhase Configuration. the word LifeCyclePhase is the name of the class and would be picked up by the view.
  • Specify fixed parameters. This would integrate the existing grid view that is displayed for classes that have user set properties.
  • Specify variable parameters.
  • Compulsory parameters. List of each [Link] IFunction stating type of link (by child etc), and reproducing the content of the summary Tag which explains the meaning of the parameter.
  • Optional parameters. List of each [Link(IsOptional=true)] Ifunction. Display default value if function is omitted. reproduce the content of the summary Tag which explains the meaning of the parameter Implementation Note defaults are dealt with in different ways in the code. Can we may need to refactor so defaults for Optionals are specified and dealt with in a consistent way and can be easily discovered by this doc system?
• General description. This would pick up the content of the Remarks tag where the class developer has provided a general description of what the class does. Ideally use same approach as auto docs so figures may be included.
• Public methods. list all public methods and a reproduce their summary tag info. Some methods subscribe to events, would be good to include what event they are tied to if poss. Perhaps this is not necessary if all methods that subscribe to events mirror the name of the event with an "On" prefix
• Model outputs. Make a table of properties with the content of their summary tags along side.

[HamishBrownPFR]

@sno036 @jbrider @hut104 FYI if you wish to comment. @hol430 I am hoping you will be able to help implement something here to get this started.

[rcichota]

This looks interesting, and will be very useful. The use of summary and remarks tags seem good in general (I have been populating summary when possible (there is a lot of too generic entries in the code) and I have used remarks quite a bit). A possible issue is that the remarks tag is/can be used for remarks made by the coder for another coder, not necessarily for user documentation. This may not be a big issue as I don't think we have used it much. However, it is my understanding that it is possible to define new tags and then use these as we do with the default ones. We could then define our own tags like "ApsimUserDocumentation" and "ApsimModelDocumentation" to use in our more specific need, instead of re-using the generic ones and risk some confusion...

[HamishBrownPFR]

Thanks for your comments Rogerio. Can you point out any reference on creating custom tags, would be a good approach.

[hol430]

Isn't this what the documentation on the website is supposed to do?

[HamishBrownPFR]

Sort of but not fully. The destruction being doco on the web site describes how a model is configured as reference for model users. The the intent here is to describe how to configure a model for model developers who build models in the UI but don't read code. One problem we have had with the online doco is getting it tidy because it is a mixture of the two intents and it doesn't address the 2nd one very well.

[hol353]

The auto-generated tutorials on the web are examples of user documentation e.g. https://apsimdev.apsim.info/ApsimX/Releases/2020.03.25.4946/Report.pdf

[hol430]

Well there's also the new params/inputs/outputs doco which was only added a few months ago. It sounds similar to this, although I suppose the main difference is that it describes the model's infrastructure/dependencies, rather than being a tutorial (also @hol353 I notice that stddev is not mentioned in section 4.1 of the document you linked).

[HamishBrownPFR]

Another important destinction is this doco is to be located on model views in the UI so it is in a handy location for developers, not generated into pdfs

[jbrider]

Sounds like a great idea - definitely needed.

[rcichota]

Thanks for your comments Rogerio. Can you point out any reference on creating custom tags, would be a good approach.

hmm, I have seen that being said in few places, especially around the xml documentation for C#/VisualStudio (e.g.: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/documentation-comments), but nowhere is shown an actual example. I have added random tags in a c# code for testing and all compiles and behaves without issues. That does not mean one can readily used them, but I'd think one can, as it it were a recommended tag. One issue is how to enforce them, or at least enforce a consistent spelling (tags such as 'summary' appear as suggestion as one types 'su..'), not sure if it is possible to add user defined tags to the list of suggestions...

[hol430]

A few implementation-related questions:

• We can use the HTMLView to render the formatted text, but it will be difficult to embed the properties input grid with the rest of the html, as in your screenshot above. We could move the properties somewhere else (another tab?) but I guess you want all of this info on the same screen
• Parsing all of this metadata using reflection and the Models.xml file may be slow, causing a slight delay when clicking on the node in the UI, similar to when clicking on the weather component. Maybe this one is a more general question - should loading of the presenter occur in a separate thread or perhaps use the async pattern?

[hol353]

• Hmmm. I don't like HTMLView. There are a lot of hacks to make it work (bit like the grid view). I don't think we have much choice though. In the screenshot above, the properties seem to be mixed in with the html which does give a nice explanation of each. Will be tricky to implement I would think. Having the properties on another tab is not what we want. If we can't embed the properties in the html then we could just go for second best and have the property view above the html view on the same page.

• For now don't worry about speed. If it turns out to be a bit slow then perhaps we can load Models.xml once at the start of the GUI so that accessing it will be quicker. We could also render the html async as you suggest.

[zur003]

It's possible to do a lot of text formatting using a Gtk TextView widget (although I don't think it handles tables), so that might be a way to avoid some of the problems with HTMLView. Although isn't the main problem with HTMLView that it's difficult to support across platforms?

[hol430]

If the TextView doesn't support tables then that's probably a deal breaker. On the other hand, the main problems I see with the HTMLView - that is, the difficulty in maintaining and extending it - shouldn't apply here as we'll just be treading the well-beaten path, displaying a few tables and headings, maybe the odd paragraph etc.

Another option would be to construct the view on the fly out of gtk widgets.

[hol430]

I've created a simple presenter which generates something vaguely resembling Hamish's screenshot above (using the HTMLView). However it's very similar to the params/inputs/outputs docs which are already available on the website. What if we just generate the params/inputs/outputs docs and render to html rather than pdf? Of course, using html still doesn't solve the problem of embedding the grid view or some other property editing mechanism into the view.

[HamishBrownPFR]

Thanks @hol430 . What you have there will be enough for me to make a start, I can have a play round with it and work out how it will or won't work. If generating the Params/Inputs/Outputs to HTML is easier or tidier happy to go with that.