Add some documentation about IDerivedStateComputer

[tfonda-fbk]

Hi,

Lately I have found this interface quite useful in the project I am working on, but it was not trivial to, first of all, learn of its existence, and then figure out how exactly to implement it. Thus, I thought of adding a dedicated section to the online documentation.

Still, there are a few things I am not sure about, so I would appreciate some feedback about the following:

• the section title;
• the usage of the preLinkingPhase parameter of installDerivedState(). Both in this example and in my project I've simply ignored it. I am unsure what could be a scenario in which considering it is a hard requirement;
• the provided discardDerivedState() implementation is very naive and does not check if an Entity's name has been manually set by the user to that of the overridden Entity plus the suffix. Preserving the name field is not strictly necessary in this case, but it would probably be more elegant to introduce a collection as a class member field, add all Entities processed by installDerivedState() to this collection, and then have discardDerivedState() only operate on the Entities in the collection.

Of course, any other feedback is welcome!
Thanks.

[tfonda-fbk]

I've just noticed I did not mention anything about the need for binding the custom IDerivedStateComputer implementation via the DSL's RuntimeModule. I'll amend my commit in the next few days.

[tfonda-fbk]

I've added a note about binding.

[szarnekow]

I don't think this example is especially beginner-friendly. The derived state is installed before the linking and here we rely on linking information to compute a name property, which in itself would be necessary to make the names that are indexed. Can you imagine a different use-case that you'd want to show here?

[tfonda-fbk]

@szarnekow
Thanks for the feedback. I've provided this example because it is very similar to what I am doing with my custom IDerivedStateComputer implementation in the project I'm working on. It seems to "just work" as expected. Are you saying that my example, apart from not being beginner-friendly, is built on wrong assumptions? This would mean that I have to rework both the example and, most importantly, the code in my project.

[szarnekow]

Yes, that's what I fear is the case.

[tfonda-fbk]

Ok. I will think of another example use case for the documentation. Though first I need to figure out how to address this issue inside my project. I already have sketched up an alternative approach that does not rely on indexing/linking-related information, although I will probably need some help to refine it. But this is off-topic here, I'll open a thread in the Discussions section. I hope you won't mind me pinging you there. Thanks a lot for your help!

[tfonda-fbk]

Hi @szarnekow
I've updated my proposed documentation section. Please let me know if this example is more suitable. Thanks!

[tfonda-fbk]

Gentle bump :)
I have at least one more documentation improvement proposal, but I don't want to flood the repo with too many PRs at once...