Better Context Help for AF Send VIs

[CaseyM]

When I create a public API method for an actor it's very nice to have the VI description populated for use with the Context Help window:

However, once you create an AF message from that method, other actors will generally be using the Send [VI Name] method instead of the payload method itself and the context help for the Send method is decidedly less useful:

Wouldn't it be nice if the send method automatically appended the payload method's VI description so it looked something like the following?

I've actually written a VI package that will do this, but in order to accomplish it I ended up modifying the MessageMakerProvider and MessageRescripter project providers. It's workable, but it's really only reliable for the one specific version of LabVIEW in which it was developed so it'd be much nicer if NI implemented this out of the box.

[D_Hooks]

Totally agree!  The current AF message scripting tool almost encourages poor documentation.  This is one of those scenarios where someone at NI could invest a modest number of hours improving the tool, and it would (1) raise the average quality of AF projects, and (2) save the community hundreds of hours of manually editing VI descriptions.  Thanks!

[AristosQueue (NI)]

There is a strong argument why this is a bad idea.

But I'm open to letting y'all convince me otherwise. D_Hooks, convincing me matters because I'm the "someone at NI" who would be doing (or not doing) this. 🙂

Replicating documentation means there are now two sources of truth. When you change the documentation of the original method, the documentation of the Send will not be updated. It is generally a bad idea to have two sources of truth for the operation of a method as it leads to confusion, especially if the fix to the documentation is to add the word "not" (happened to me recently!).

> (2) save the community hundreds of hours of manually

> editing VI descriptions.

An activity that I don't think you should be doing in the first place.

> The current AF message scripting tool almost encourages

> poor documentation. 

No. The current AF message tool encourages a user to go check the documentation on the invoked method. Providing wrong documentation is significantly worse than providing no documentation.

> (2) save the community hundreds of hours of manually

> editing VI descriptions.

An activity that I don't think you should be doing in the first place. There... I've saved you time already. 🙂

HAVING SAID THAT... I get why you're asking for this feature. The primary call site is the Send method, and that's likely also what is in the palettes, and having useful Context Help there is important. So, maybe this would be an option?

Possible compromise:

If the message is intended to become the primary way that a method is invoked, we could have creating a message remove the documentation from the method VI and move it to the Send VI. The method VI could be updated by the scripting tool to say, "This method is invoked through sending a message. See the Send ____ Msg.vi for details of operation."

Since in most cases the only caller of the method of an actor is the Do.vi of the message, there's less need for an easily accessible Context Help there.

How does that strike you?

[PNR]

Perhaps MGI Actor Framework Message Maker is what you are looking for.

https://www.ni.com/en/support/downloads/tools-network/download.actor-framework-message-maker.html

Not only does it copy VI documentation to send messages, it also handles the VI icon and allows to batch update/rebuild messages. I have been using this tool for the past few years and never spend time on updating documentation or icons on send message VIs.

[drjdpowell]

A more far reaching solution to this problem would be some kind of new "send message" structure (visually similar to an in-place structure) that takes an enqueuer input and allows one to drop the actor method(s) you want called in it.  Then the documention is right there.  

Of course, I'm sure AQ has considered this but it would be considerable effort.

[AristosQueue (NI)]

drjdpowell: Not possible. The activity inside a Do.vi is usually just a method call, but it can just as easily be something more or less complicated -- possibly a whole stream of messages, for example. Handle Message.vi is dynamic dispatch and might not even call a Do.vi. There's no guaranteed 1-to-1 relationship for all message types.

[CaseyM]

---

The current AF message tool encourages a user to go check the documentation on the invoked method.

---

Ugh.Without any scripting tools to help with this, then the quickest way I can think of to get to the payload VI and check documentation is to:

1. Open the Send VI.
2. Locate the Send VI in the project.
3. Open the Do VI's front panel.
4. Open the Do VI's block diagram.
5. Use the context help to get the payload VI's description.

If you want to reduce the number of steps (at the expense of time and mindshare IMO), I suppose you could:

1. Switch to the project window.
2. Bring up the search dialog and search for the name of the payload VI (assuming there's only one VI with that name).
3. Use the context help on the results.

Either way, don't you think needing this many steps to do something as straightforward as read a VI's documentation is silly? Also, I'm sure I'm not the only one who has multiple VI FPs and BDs open at once. If I were to use the first procedure that I listed to get to the payload VI, I'd end up with potentially 4 windows overlapping the block diagram where I actually do the call so now I have to spend even more time getting back to my block diagram eventually. Each single step might be small, but it adds up.

---

Possible compromise:

If the message is intended to become the primary way that a method is invoked, we could have creating a message remove the documentation from the method VI and move it to the Send VI. The method VI could be updated by the scripting tool to say, "This method is invoked through sending a message. See the Send ____ Msg.vi for details of operation."

Since in most cases the only caller of the method of an actor is the Do.vi of the message, there's less need for an easily accessible Context Help there.

How does that strike you?

I don't like this either. I don't think it's uncommon to use the payload method within the owning actor directly as a sub VI call on the BD. For example, say I have an actor that controls an XY stage. Now it's perfectly reasonable that I have the following API methods:

1. Move to XY Position.
2. Perform Serpentine Map.

In this example, method 2 could very well contain a series of calls to method 1 and I might want to guarantee that those calls are not interrupted by any external callers so I'd use "Move to XY Position" as a sub VI on the BD.

Ultimately, it doesn't strike me as asking too much of the developer to remember to rescript their AF messages if/when they change their documentation. Developers already know they have to rescript messages if the connector pane changes. We also ask developers to remember to update VI descriptions and VI icons when they make a copy of a VI as a starting point for another or they'll end up with wrong documentation. Why is asking them to remember to rescript a message when a VI description changes such a big ask?

[CaseyM]

---

Perhaps MGI Actor Framework Message Maker is what you are looking for.

https://www.ni.com/en/support/downloads/tools-network/download.actor-framework-message-maker.html

Not only does it copy VI documentation to send messages, it also handles the VI icon and allows to batch update/rebuild messages. I have been using this tool for the past few years and never spend time on updating documentation or icons on send message VIs.

---

Yes, I'm aware of this and some other tools like it, but for something so seemingly basic, I'd rather see a native implementation by NI rather than relying on a 3rd party tool that might break between versions of LabVIEW.

[drjdpowell]

AQ: note I proposed a structure, so one could place any code you want in it.  The code you would put in the Do method would be right there in this structure instead.  Basically I am suggesting not having an explicit message class at all.  

[drjdpowell]

Another suggestion is making a right-click item called "Open Do.vi".  Called on any library method, this would open the block diagram of the Do.vi method of the same library.  This means fewer steps to see the actor method description.

[AristosQueue (NI)]

> Ultimately, it doesn't strike me as asking too much of the developer to

> remember to rescript their AF messages if/when they change their

> documentation.

I deal with the complete breadth of customers. This would be a pretty high burden for many, possibly most, in my judgement. It would definitely be a performance hit on re-distribution unless we introduced specifically a new right-click for "Update documentation only" to avoid rebuilding the whole VI. There's a lot of "ick" in this solution to me.

What we probably need is a whole different Idea Exchange entry that is "Let me put some tag in Context Help description of VI X that tells LV to copy all the text from VI Y into this location when it is displayed in the CH window." AF would then set the text of the Send VI to be "Sends the message to trigger the following method: <VI=".\relativepath\Method.vi">"

If the target VI cannot be found then it might sub in "[Cannot find .\relativepath\Method.vi at that path]"

Could imagine it going further with <VI=".\relativepath\Method.vi" Section="Main">. And then in the Method.vi, you might have text that is surrounded by <Main> </Main> and that would be the text borrowed instead of the whole CH.

Obviously this would be a much larger LV change than just rescripting the CH, but would solve the "two sources of truth" problem, avoid introducing another reason to re-script, and would have wider utility beyond the AF.