Atlassian Confluence \ JIRA \ LabVIEW Class Auto-documentation APIs and Examples

[Chris_Cilino]

Description

Description-Separate-1

Author: Chris Cilino, CLA \ LabVIEW Champion, Center Of Excellence Technical Lead
NI Product(s) Used: LabVIEW
Industry: Semiconductor

---

The Challenge

To reduce the barrier to complete documentation by augmenting manually generated documentation in our Confluence wiki with automatically generated documentation for LabVIEW classes. Any documentation that's missing from classes should cause the generation of a JIRA ticket with detailed information about whats missing.

The Solution

I've created a scalable \ extenisble auto-documention API and an extensible set of Atlassian APIs (Confluence and JIRA) to automatically generate documentation for LabVIEW classes and host the report in a Confluence page. 

Introduction

One of the software engineering best practices is to clearly document the different facets of our classes, including

1. Class Charter
2. Class Location on disk
3. Private Data information
4. Member information

While this documentation can and does exist in the class itself, it's helpful to have a summarized report in a Confluence wiki, allowing anyone to view the capabilities of the classes in one, company wide accessible location without needing the LabVIEW IDE to view the class documentation. 

Filling in class documentation often times is only partially completed. Therefore I've also created a JIRA API that allows us to audit and create tickets clearly indicating what the problems are with the documentation. While the first application of the JIRA API is to file tickets for documentation, it is written in a completely generic way.

Application Description

 In order to maintain a separation of concerns, the APIs and the example applications are completely independent. Therefore the APIs controlling confluence and JIRA can be used in any other application.

I've also created an API to programmatically create reports. The report API (as well asl the other APIs) is object oriented. The first child of the API is to generate reports for LabVIEW classes. The API can be extended to any LabVIEW element supported by VI server such as, VIs, ctls, lvlibs, etc.  

The example programs I've included utilize very simple architectures. Both are "single shot", meaning the parameters (such as Confluence login credentials) are entered at edit time and then code is run without an event handler to service user input at runtime. 

The UML diagram below summarizes the relationship of the classes I've created.

The outer dotted boxes denote lvlibs. 

 

Impact/Results

Using the APIs and small applications included in the attached zip files, you can easily create reports in the format you see below:

Description	Image
A Confluence Class Report contains the Charter, Disk Location, Private Data Members, and Methods of a LabVIEW Class. Private Data describes the name, description and data type of all private data of the class.
Name describes the data structure of the data. "{}" indicates a cluster. An element of a cluster is "{}.name"
LabVIEW Classes with their own documentation are automatically linked to their respective class documentation pages.
"[]" indicates an array. An element of an array is "[].name".
"*" indicates a reference. The element referred to is "[].name"
Typedefs are described as "TypeDef "Name of .clt": Data type. If the .ctl is an enum the data type of the enum is reported and the {Value : Text} pairs
The individual members of a class are listed in a table with detailed information.
The JIRA API allows creation of tickets with the following form:

Storing Documentation Locations in the Item being Documented

Each item (like class or project or VI) knows where it's documentation is located by virtue of tags. This is a little know way of associating metadata with LabVIEW files \ objects, like classes or projects or VIs or controls. You can access class tags using the following invoke nodes:

I've designed a tagging system to tag the location of every report\printout combination. The system is

<G3GlobalTag>:-:G3AutoDocPrinterReportComboTag:-:<ReportClass>.lvclass::<PrinterClass>.lvclass

As an example:

G3Tag:-:G3AutoDocPrinterReportComboTag:-:G3_Documentation Reports.lvlib:Class Report.lvclass::G3_Documentation

Reports.lvlib:Confluence-JIRA.lvclass

As a result any combination of report \ printout is saved to the item (if the printer deems it important to do so). And each item can be asked for its documentation of a specific type. This is a scalable system to embed all locations of documentation in source. The VI most directly for saving the tags is

"user.lib\_Cirrus Logic\LabVIEW Auto Documentation\Source\Report\Abstract\APIs\Print.vi". In previous versions of this utility, the "Help tag" was used to store the information.

You'll need to edit your code in the following locations for the auto-generation utility to pick up the text

Item Being Documented	Source of Information
Class Charter
Private Data Name
Private Data Description
Private Data Descriptions for Classes in DVRs	For private data members of classes in DVRs, copy the object out of the DVR, edit the class description, then drop it into the DVR.
Scope	Setting Member Scope
Dynamic Dispatch	Setting Dynamic Dispatch
Must Override	Creating Member VIs
Must Override - Reason	If any class member is marked as "Require descendant classes to override this dynamic dispatch VI" use the XML tag "<RequiredOverrideReason>[content]</RequiredOverrideReason>" in the VI's documentation. In this tag describe the reason for requiring an override.
Must Use Parent	Creating Member VIs
Must Use Parent - Reason	If any class member is marked as "Require overrides of this dynamic dispatch VI to always invoke the Call Parent Method node" use the XML tage "<MustCallParent>[content]</MustCallParent>" in the VI's documentation. In this tag describe the reason for requiring the method to call its parent.
Member Description	Setting VI Descriptions

Conclusion

The APIs are in their infancy. However, even at this early stage, they provide a tremendous benefit to me and should also prove useful to the LabVIEW community at large.

Author Contact Details

My Champion's Profile

Description-Separate-2

[Albert.Geven]

Thanks Chris After my holidays I take a look.

[Paul-D]

Thanks for sharing @Chris_Cilino!

[richardscheff]

Thank you.  I was wondering how the progress is going with project report.  It would be a huge benefit to many.  

[Chris_Cilino]

@richardscheff,

You're welcome! I actually just released a new version yesterday. I've made some improvements and fixed a few bugs. Enjoy! And again, my thanks to @soliton for their contribution (https://www.solitontech.com/)

[SriAtluri7]

Great stuff, Chris! Is there a way to simply print to text/ PDF/ word file instead of publishing to Confluence/ JIRA?

[t.kendall]

Chris

I am wanting to use this and I was wondering if we could put it up on github or something so I can feed my changes back in for the community? 

Building in the 2FA stuff.

[Chris_Cilino]

@SriAtluri7, While there isn't an implementation for txt / pdf / word file yet, those can be written by extending the printer class. I'm thinking about writing a printer to print to bitbucket for my new repository at https://bitbucket.org/ChrisCilino/labview-auto-documentation/src/master/. The repository is still a work in progress. I'm currently creating the wiki and designing the system by which the software and its dependencies can be downloaded. Ultimately I hope to use GCentral to distribute the software but it isn't quite up and running yet. The installation procedure (Under Construction ) contains the info to get the AutoDocumentation Utility.  

[Chris_Cilino]

@t.kendall,

I'm in the midst of transferring the source to bitbucket. Check out

https://bitbucket.org/ChrisCilino/labview-auto-documentation/src/master/