code commenting feature request

[david_jenkinson]

Hello, It seems like it sure would be neat to be able to highlight, or box around with a raised box, or other visual means to highlight a section of code in the diagram and comment it.  Right now, I am just using comment text block with number designators and descriptive text, then I pepper numbers all over the code requiring referring back to the comment code block.  The problem is the numbers don't really tell exactly what code the comment refers to, but it does a rough job just by the fact it is geographically close to the code that is being commented.  It seems like this would just be another palette similar to what the front panel has to isolate front panel controls and decorate it, but with the ability to associate comment text.  Is there  something like this already I am just missing?David Jenkinson

[smercurio_fc]

There is a flat frame decoration that you can use on the block diagram. Structures -> Decorations -> Flat Frame. Is this what you were thinking of?

[Ben]

Most of the decorations are'nt very useful but if you select them on the FP and drop them on the BD you can use them.
<img src="Loading Image...">
BenMessage Edited by Ben on 08-04-2008 06:40 PM


decoration.PNG:
http://forums.ni.com/attachments/ni/170/346509/1/decoration.PNG

[Ravens Fan]

Ben wrote:


Most of the decorations aren't very useful but if you select them on the FP and drop them on the BD you can use them.



You can also get to the decorations from the Programming palette in the BD by way of Structures then Decorations.&nbsp; At least in LV 8.5.&nbsp; It saves switching over to the FP then back. :smileywink:Message Edited by Ravens Fan on 08-04-2008 10:42 PM

[david_jenkinson]

I still can't help but think it would be nice to have a dedicated "comment" frame, that had text tied to it, maybe dockable to whatever side you want, rather than separate from the frame.&nbsp; Being separate from the frame lends itself to possibly getting unintentionally moved away from the frame it refers to.&nbsp; It could perhaps be half opaque, as to not be too intrusive to the diagram logic itself, but enough to know it is there so that when you click it becomes complete opaque and readable.&nbsp; The frame/arrow thing seems kind of clunky to me.&nbsp; Proper commenting is something I've come to grips with in the last couple years, so I do a fair amount, and the way it is now just seems lacking somehow. Dave

[tst]

The label (as Jon mentioned) is associated with the structure and labeling while loops, for instance, is reasonably common. You can manipulate the label to look nicer.
As for the suggestion I gave earlier, here's an example implementation (7.0). If you add this VI to your palettes as a merge VI, you can then drop it and right click it to edit the description property, which will appear in the help window.


Comment_Image.vi:
http://forums.ni.com/attachments/ni/170/346804/1/Comment_Image.vi

[david_jenkinson]

I am unfamiliar with adding to the palette as a "merge vi".&nbsp; I'll have to research this.&nbsp; I know you can have user libraries, but I take it this is different.&nbsp; I'll research the help.

[tst]

<a href="http://forums.ni.com/ni/board/message?board.id=170&amp;message.id=237642" target="_blank">Here</a>'s a quick link you can start with.

[david_jenkinson]

hmm ya I guess that's kind of what I meant.&nbsp; Didn't notice that before.&nbsp; Been using LV since 4.1, when did that happen? Thanks

[tst]

The problem with the function palettes decorations is that there is less of them (although you do have the arrows).
Generally, for something like this, a visit to the <a href="http://digital.ni.com/applications/psc.nsf/default?openform" target="_blank">Product Suggestion Center</a>&nbsp;helps better.
As an alternative, create a VI with a string constant, make it large enough and color it in a prominent color (or use&nbsp;a LabVIEW class constant, if you want a specific design). You can now make a merge VI out of it and drop it whereever you want. After you drop it, you can edit the constant's description property, which will appear in the context help menu.

[Ravens Fan]

tst wrote:

The problem with the function palettes decorations is that there is less of them (although you do have the arrows).


You're right.&nbsp; Putting decorations on the block diagram is something I've done very rarely, but I had done it recently and realized it was there.&nbsp; Pretty much just to point out something in a block diagram for a reply to someone's message in the forum.&nbsp; And it seems like the BD decorations pallette as all that you would need for that (labels, boxes, arrows and lines.)&nbsp; The extra stuff in the FP decorations pallette is good for adding graphic features to a front panel, but probably have no real use for documenting a block diagram.

[Mythilt]

One could also surround the code with a single frame sequence structure and then set the structures label to visible and comment using that.&nbsp; (I usually do a single line comment on my loops this way.)

[TonP]

Some (little known) coding tips: -Show the label of loops for documentation-Put comments on a wire (right click-&gt;description), this shows up in the online help (ctrl-h)-Use enums-Use sub-VIs, every sub-vi should have a meaningfull icon and description-Use the description of controls and indicators including limits that normally applyTon

[nrp]

right-click --&gt; wire descriptions great suggestion, somehow I missed this totally in all my time of using LV!&nbsp; Thanks!!!

[WilliamLee]

One suggestion that I had mentioned before would be a documentation system similar to doxygen, that can generate XML, HTML, PDF, etc.. type help.&nbsp; A simple documentation box is like a label and can not be easily reused to generate documentation in another form (report, web, etc.)&nbsp;
Will
&nbsp;

[tst]

Recursively parsing the diagram for all the comments should be relatively easy using private properties, but what would you do with the text once you had it?

[WilliamLee]

You could generate documentation to help describe the code (such as what NI does with its help) to users of the VI.&nbsp;
&nbsp;
The documentation could be formatted as:
&nbsp;
VI name
&nbsp;
Small Diagram showing inputs
&nbsp;
Inputs
&nbsp; --- -------------------------

&nbsp; --- -------------------------

&nbsp; --- -------------------------
&nbsp; --- -------------------------
&nbsp;
Outputs
&nbsp; --&nbsp; --------------------------

&nbsp; --&nbsp; --------------------------
&nbsp;
Description
&nbsp; blah blah blah blah
&nbsp; blah blah blah blah
&nbsp; blah blah blah blah
&nbsp;

[tst]

The comments I use in my code would usually not fit as a description for the VI. On occasion, I duplicate some of the text in the VI description by copying and pasting it, but I don't see a reason to do it automatically. That's what we have the VI description for.

[smercurio_fc]

But you already get this from the built-in printing of the VI documentation, so what are you gaining?

[WilliamLee]

I find it useful to generate paper/PDF documentation and also searchable HTML or the Microsoft CHM format help.&nbsp; Also, by generating the documentation into an markup language like XML, you can process it to generate/format the documentation how you want it (for example, company icon at the top, consistent formatting for headings from other reports).
&nbsp;
Plus, better integration with other documentation systems (which work primarily on text-based languages) would help consolidate and streamline&nbsp;the developer toolchain.&nbsp;&nbsp; This is just my idea; I don't know how well it would work on VIs (which are binary).