Add statement on explicitly returning nothing in control functions

[BSchilperoort]

Ref csdms/bmi-example-julia#8

I added a general statement in the initialize docstring to avoid too much repetition.

[BSchilperoort]

Working on the implementation in csdms/bmi-example-julia, I realize that initialize needs to return the model. I could have also looked at #1 of course.

[visr]

Ha interesting that you chose initialize, since that is the odd one out in this case I believe, see #1 (which I now see you just found). Perhaps we could document that if a type is passed, we return the model, but if a model is passed, we return nothing.

I think I'd prefer the repetition in this case though, since I don't think we can necessarily expect everyone to read the initialize docstring first.

[BSchilperoort]

Perhaps we could document that if a type is passed, we return the model, but if a model is passed, we return nothing.

I think consistency would be best here, i.e. always return the model.

In what case would you already have the model instantiated, and would want to re-use the struct to initialize it again? I'm having a hard time picturing that.

[visr]

always return the model

Yes that's also fine by me.

In what case would you already have the model instantiated, and would want to re-use the struct to initialize it again?

Yeah I was thinking of some constructor that has empty arrays, which are then filled with initialize or something like that. But I don't really think it is needed, and I see bmi-example-julia, Wflow and Ribasim all only have the method on the type and not the instance. So perhaps a better way to resolve #1 would be to document that this is the only way: BMI.initialize(::Type{MyModel}, config_file)::MyModel.

[BSchilperoort]

would be to document that this is the only way: BMI.initialize(::Type{MyModel}, config_file)::MyModel

To add these types, I'd have to define a MyModel struct. Shall I do that and also add types elsewhere?

[visr]

Ah I meant to only document this. The MyModel struct example is not for BMI.jl but for users of BMI.jl.

[BSchilperoort]

@visr I've added an example implementation to initialize that should hopefully clear up any confusion.

[BSchilperoort]

I do see that in Wflow.jl and Ribasim you don't actually use the model's type, and that it's only passed so that julia uses the correct function. Maybe it's good to actually clarify that.