Example Program Drafts

cancel
Showing results for 
Search instead for 
Did you mean: 

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

 Company: Cirrus Logic
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 of our validation system 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

 As a LabVIEW Center of Excellence at Cirrus Logic, the G3 team uses software engineering best practices to produce and maintain high quality software for our validation team. 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 our 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. 

 

We recognize that 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.2019-04-05_11h00_47.png

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.

2018-07-20_15h50_26.png

Name describes the data structure of the data.

"{}" indicates a cluster. An element of a cluster is "{}.name" 

2018-07-20_15h50_48.png

LabVIEW Classes with their own documentation are automatically linked to their respective class documentation pages.

2018-12-20_15h27_46.png

"[]" indicates an array. An element of an array is "[].name".

 

2018-07-20_15h51_02.png
"*" indicates a reference. The element referred to is "[].name" 2018-07-20_15h51_09.png
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 

2019-03-01_09h43_57.png

 The individual members of a class are listed in a table with detailed information.  2018-07-20_15h51_19.png
The JIRA API allows creation of tickets with the following form: 2018-07-20_15h54_36.png

 

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:

2018-12-20_15h33_39.png

 

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 image2018-7-24_13-4-31.png
Private Data Name image2018-7-24_13-6-13.png
Private Data Description


image2018-7-24_13-6-49.png

 

image2018-7-24_13-7-26.png

 

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.

2018-07-27_16h02_32.gif

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 Cirrus Logic and should also prove useful to the LabVIEW community at large.

 

Author Contact Details

My Champion's Profile

 

Release Notes 

1.2.0-6:

  1. Added examples to generate documentation \ JIRA tickets for Libraries and projects. 
  2. Fixed a bug for printing jira ticket documentation for libraries \ projects. 
  3. Improved error handling for libraries \ projects.

1.2.0-2:

  1. Can now point to a lvproj, lvlib, or class to create documentation for each type. Pointing to a Project documents all elements of that project including lvlibs and classes. Pointing to a lvlib documents sub lvlibs and classes.

 

1.1.0-29:

  1. Fixed enum in private data so that now there is a carriage return for each element
  2. Added an assumption for the private data that if a class uses another class, it is assume that the used class' documentation is in the same Confluence space as the user class'  documentation.
  3. Added Build instructions to be used in conjunction with the Component Builder system.

12_20_2018:

  1. Added the concept of a printer. In previous versions, generating the report would embed the report into a confluence page. This was the only option. In this new release, a "print" prints the report in various forms. I've implemented the confluence and JIRA printers.
  2. Changed the system by which a thing (such as a class) knows where its documentation is. Now the tag system is use and one tag is given per documentation location. Each location corresponds to the combination of report type and printer type.
  3. The report has been given the notion of a "sub report". So a project can construct class reports. Each report is responsible for constructing its own sub reports.
  4. This is a partially complete release. The project report is NOT complete. However the abstract report and printers are complete.
  5. The examples have been embedded in the source of the Autodocumentation vip. See the readme for details on the locations.

10_11_2018:

  1. Added the ability to include hyperlinks in documentation that will translate into links in generated documentation. Use "examples\General Get URLs and XML Docs Links.VI." to get translate the text into the xml tags to insert into your documentation.
  2. Formatted Enums better in datatype representation.
Comments
Trusted Enthusiast Trusted Enthusiast
Trusted Enthusiast
Thanks Chris After my holidays I take a look.
greetings from the Netherlands
Example Gatekeeper
Example Gatekeeper

Thanks for sharing @Chris_Cilino!

Paul Davidson
National Instruments
Senior Business Manager - Web Product Documentation
Member richardscheff
Member

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

Active Participant Chris_Cilino Active Participant
Active Participant

@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/)

Member SriAtluri7
Member

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

Contributors