[Documentation] Questions concerning MatchAdapter

[anthonyanjorin]

I'm creating this as an issue so you know what questions your JavaDoc documentation should answer...

Concerning the getGraph method for MatchAdapters:

1. Do I have to build the entire graph consisting of both rule and match?
2. Domain and action for match nodes/edges is rather weird... Isn't this clear from the corresponding rule nodes?
3. What does neighbourhoodSize mean?

[LegionaryCohort]

I've added some explainations to the Javadocs regarding these questions.

However, regarding number 2:
Victory's new visualisation system is quite flexible in that it simply displays whatever the adapter tells it to display. This provides a lot of flexibility when building graphs, allowing for example semi-dangling edges (i.e. edges that have a src and trg node, but those nodes are not necessarily both part of the node-set of the graph). However, the downside of this is that it is necessary to specify the domain and action explicitly, as Victory will not derive them automatically from relationships between nodes that go beyond simple graph information.

I'm not sure where to put this information in the Javadocs however. Perhaps in the docs for the Graph API?

[anthonyanjorin]

Yes, the Graph API would make sense.

Something I found confusing: Victory doesn't seem to distinguish between "rule" graphs, and "model" graphs. This means that model (match) graphs have properties (action) that don't really make sense... You should explain in the API how this stuff is handled (or perhaps introduce RuleGraph, ModelGraph? Or throw an exception?). Domains for model graphs is also strange (as it is more a rule concept -- some crazy tool might match source and target rule variables to the same model element).

I agree, however, that simplicity is great... and the visualisation should not pose too many clever restrictions.

[LegionaryCohort]

Yes, Victory only knows graphs that have nodes and edges, and it offers a number of ways to customize how those nodes and edges are drawn. If we were very precise, then Victory shouldn't really have any concept of Domain or Action at all, as they are just indicators for the coloring of background and foreground, respectively.

Ideally Victory should just ask the adapter for the foreground and background color of each node, and then the adapter can deal with concepts like domain and action, but I don't think that's a change we can get implemented properly by tomorrow.

[anthonyanjorin]

Final conclusion: it would be nice to use terms like "BackgroundColour", "ForegroundColour", etc as opposed to "Domain" and "Action"...