====== 03 Documentation ======

===== Comments =====

  * Comments should explain the „why“, not the „how“
  * Using hashtags (see below) enables [[kb:labview:bookmarks|Bookmark Manager]] usage


=== Comment Colors === 

^Description  ^RGB Color Code  ^LV-internal Color Name  ^
|@#ffffd7:NI Default  |''255/255/215''  |---  |
|@#91FBFE:NI Code Recommended      |''145/251/254''  |"template comment" |
|@#FFB32A:NI Example Code          |''255/179/42''   |---  |
| |||
|@#6c0080:<color white>HSE</color>   |''108/0/128''      |---  |
| |||
|@#ADB4D3:DQMH HowTo            |''173/180/211''  |"tank housing"   |
|@#88FFD7:DQMH MHL              |''136/255/215''  |---  |




===== Hashtags =====

|#docgen XX	|Functional description of VIs. Optional: Sequenced with numbers starting with XX=01  |
|#todo-abc	|Functionality is missing. Optional: Append intials (3 letters) to #todo for personalization  |
|#fixme 	|Errors that need fixing  |
|#coderev	|Remarks during Code Reviews  |
|#optimize	|Potential for optimization (v.A. FPGA)  |
|#covers        |Marks code that directly deals with a certain requirement   |
|#HSE           |Code specific to the HSE way of working in our templates   |
|||
|#DQMH_Howto    |Code specific to the HSE way of working in our templates   |
|#CodeRecommended          |Code specific to the HSE way of working in our templates   |


===== Labels =====

  * Case Structures 
    * Display label and put a question describing the purpose of the case structure
    * Display subdiagram labels and answer the question for each case
    * Optional: Color the expected case(s) - the "sunshine scenario" - in light green (RGB = 225/255/225)
    * Optional: Color errors in light red (RGB = 255/225/225)
    * {{:kb:bestpractices:case-structure.png?600|}}


  * Subdiagram Labels are to be displayed and filled with text
    * Exception: Error Structures
    * Tools -> Options -> Block Diagram -> Tip Strips & Labeling -> Subdiagram Labels visible by default

  * Constant Labels are to be displayed and filled with text
    * Tools -> Options -> Environment -> Show created constant labels


===== VI Properties =====

  * „File -> VI Properties“ or „<Ctrl>-I“
    * Select category „Documentation“ 
    * „VI Description“ contains the text that is displayed in the context help window


===== Quickstart Template VIs =====

[[code:common:project-structure#vi_templates_directory|Quickstart VIs]] will have a comment placed on their block diagram as follows:

    This is a quickstart VI: A very simple example for using this package.
    
    This project ships with several examples which you can browse from 
    the Example Finder ("Help -> Find Examples…" menu item in the LabVIEW IDE).
    In the NI Example Finder, browsing the directory structure, navigate to "\HSE" 
    or "\Hampel Software Engineering" where you will find additional example VIs.


===== Projects =====

  * Every project needs a readme.md
    * sits at the root of the repo
    * describes the basic structure
    * links to resources (like hie-libs documentation)
    * lists dependencies and requirements (also .vipc?)

===== UML =====

Use [[https://plantuml.com/|PlantUML]] for server-side generation of diagrams from plain markdown text. Both Dokuwiki and Gitlab support PlantUML.

=== GitLab Syntax ===

    ```plantuml
    @startuml
    Alice -> Bob: Authentication Request
    Bob --> Alice: Authentication Response
    Alice -> Bob: Another authentication Request
    Alice <-- Bob: another authentication Response
    @enduml
    ```

=== DokuWiki Syntax ===

    <uml>
    @startuml
    Alice -> Bob: Authentication Request
    Bob --> Alice: Authentication Response
    Alice -> Bob: Another authentication Request
    Alice <-- Bob: another authentication Response
    @enduml
    </uml>

//See [[processes:dokuwiki#plantuml|Processes/Dokuwiki]] for a rendering example.//


===== External Info =====

  * If there is an external source of information, then mention it or link to it on the block diagram
    * eg when reimplementing an algorithm from a text-based programming language, add a screenshot of the code fragment
    * when working towards external specifications (eg implementing a protocol), link to the official documentation


---- 

===== VI Documentation Generator  =====

  * Generates dokuwiki pages from VIs
  * see https://code.hampel-soft.com/hse-labs/documentation-generator/ repository


---- 

<block 100%:0:#FFF8FF;#800080;1px dotted #800080;Arial, Helvetica, sans-serif/10ptrounded>**[[https://createbettersoftware.com|The HSE Way of Working]]:** \\ 
A set of guidelines that recommend programming style, better practices, and methods for all our LabVIEW projects. We ask all our peers to follow these guidelines to help improve the readability of our shared source code and make software maintenance easier.</block>

|< 100% 50% >|
|[[kb:bestpractices:codingconventions:layout-design|<< 02 Layout & Design]]  |  [[kb:bestpractices:codingconventions:errorhandling|04 Error Handling >>]]|