@Taggart wrote:
I inherited an AF program with minimal documentation. What kind of documentation do you guys find useful and how do you go about generating/creating it?
In DQMH I would just run Anti-doc as a good start. I tried that here and it does generate some class UML diagrams, but not very useful.
I started drawing out an actor tree. I also expanded the built-in class heirarchy to get an idea. I may run the GOOP UML modeller. That's all static though.
When it comes to sequence diagrams, what are people's preferences? Would you start trying to create your own or would you run the Python tool that uses AF debug to capture the actuals? I assume that might be easier.
Also has anyone found a good way to look at an Actor and figure what all messages it can recieve/send? In DQMH I can simply look in that library and it is all there. In AF, due to inheritance, it's kind of spread out. Anyone have any tools or shortcuts for figuring that out? Is there an easy way to see what all messages a particular actor responds to? Or am I just stuck going through each actor in the heirarchy and trying to maintain that in my head? If I have to do it manually, anyone have any particular form of diagramming this that makes sense?
I've been trying to use the C4 Model, as it makes the most sense to me - going from the system-boundary view of context diagram to required level of detail in the code diagrams. I started using mermaid.js early this year due to:
- Ease of creation: As the authors state, it uses markdown-ish syntax. Any text editor can be used for editing; and one's favorite browser for viewing.
- No need to worry about accurate placement of items.
- Ease of storage in repo: A minified javascript file can be stored along with the HTML file(s). Completely self-contained, even if authors come out with new versions of their library.
- Ease of transmission: A PDF 'print' from browser takes care of that.
- Ability to embellish with standard HTML for a more 'comprehensive' document: Contents, link traversal, etc.
- Autonumbering of messages in sequence diagram, for easier reference during design conversations.
- Live editor.
There are a few possible downsides.
- A bit of learning curve in HTML, if one is not familiar with it,
- While the basic mermaid js syntax is straightforward, more complex variations will involve a bit of learning curve.
- Limited variety in diagrams,
- Placement of items may be sub-optimal. Sometimes, I've had to break down a diagram as it was 'too wide' or 'too tall' to meaningfully read. This is also likely designer error in partitioning information.
I started to create a LabVIEW script to traverse a LabVIEW project to create the HTML document. Got as far as creating a single class box with its data members and methods, including access scope and dispatch type. Further activity got shelved due to other priorities.
I agree that the Actor tree, class and sequence diagrams pretty much convey the bulk of code-specific information. I have looked at UML Communication Diagrams, but mermaid.js doesn't support it. Additionally, the sequence diagram is easier to follow due to familiarity. (By the way, that last link is one of the first I found in a search engine. I attach no other importance to it nor the vendor.)
Regarding messages that an Actor can receive, I guess one could script a search for the callers of that Actor's public method VIs. Those name '<methodName> Msg.lvclass' would be the desired messages. (Of course, I'm assuming that NI's AF scripting tools have been used to create the messages.) This would cover messages within the Actor's lvlib; as well as those in LV2020+ interfaces; as the Actor would have overridden those VIs.
Regarding messages that an Actor sends, one could script a text search for all the directly-called subVIs named 'Send <messageName>.vi' in all of its method VIs.
On a similar note, I guess one could start with the Root Actor; and script a search for 'Launch Nested Actor' calls therein to dynamically build the Actor Tree. Not sure how fast or slow such an algorithm might be though.
