doc: Introduce Help field in YAML doc

The reason is that I want to automatically generate both MaskDescription
and MaskHelp. Currently, these two things are often not consistent. For
now Help is set to be equal to Description, but in a future, Description
is supposed to be shorter (and displayed just in Simulink block),
whereas Help will be longer and will be used also in printed
documentation.

diff --git a/rpp/blocks/scripts/schema.yaml b/rpp/blocks/scripts/schema.yaml
index 11e6810a754e68fdd0b60e49e040f747b381aed9..afbc723ae6fb203f42e712615a667902f070340b 100644 (file)
--- a/rpp/blocks/scripts/schema.yaml
+++ b/rpp/blocks/scripts/schema.yaml
@@ -18,7 +18,8 @@ required:
             range: //str
   Outputs: *iodef
   Parameters: *iodef
-  Description: //str
+  Description: //str            # Only for desciprion in block properties
+  Help: //str                   # For help window and printed documentation
   Status:
     type: //rec
     required:

diff --git a/rpp/blocks/sfunction_ain.c b/rpp/blocks/sfunction_ain.c
index 79eff0dff0a604652cf246897a409e5e7560738c..0ee0831100885cf009bcd9e6fb62e3a833afcf18 100644 (file)
--- a/rpp/blocks/sfunction_ain.c
+++ b/rpp/blocks/sfunction_ain.c
@@ -37,8 +37,8 @@ Outputs:
 Parameters:
   - { name: "Pin number", type: "uint8", range: "[1–12]" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to read the analog inputs on the RPP board. The
   ErrFlag should if raise `rpp_adc_update()` or `rpp_adc_get()`
@@ -48,6 +48,8 @@ Description: |
   always be 0. Because the ErrFlag should never set, once set the
   following steps will never clear it back.
 
+Help: *desc
+
 Status:
   Tested:
     - Changing the pin.

diff --git a/rpp/blocks/sfunction_aout.c b/rpp/blocks/sfunction_aout.c
index 62b4ceaf8ae84c892566f2ffebf7b6a47e6850be..186a92c9c8999707b176e06995075ed94d1375ed 100644 (file)
--- a/rpp/blocks/sfunction_aout.c
+++ b/rpp/blocks/sfunction_aout.c
@@ -38,8 +38,8 @@ Parameters:
   - { name: "Pin number [1-4]", type: "uint8" }
   - { name: "UseVoltage",       type: "bool"  }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   Sets the analog value of the specified analog output pin on the RPP board. If an error is detected 
   while setting the value, the ErrFlag is set high.  
@@ -56,6 +56,8 @@ Description: |
   Because of this, the outputs of the DACs are initialized on the first step of the model and not on 
   the model initialization.
 
+Help: *desc
+
 Status:
   Tested:
     - Changing the pin, voltage/value flag.

diff --git a/rpp/blocks/sfunction_canreceive.c b/rpp/blocks/sfunction_canreceive.c
index b503f63584d4b87d0985097a13dda3ff23c97c27..dfeee1be478f060c873e1e7105b1a468fa7246db 100644 (file)
--- a/rpp/blocks/sfunction_canreceive.c
+++ b/rpp/blocks/sfunction_canreceive.c
@@ -44,8 +44,8 @@ Parameters:
   - { name: "Automatic mailbox number", type: "bool"                                                     }
   - { name: "Mailbox number (0-31)",    type: "int8"                                                    }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows receiving messages from the CAN bus. It can be
   configured for any of the CAN ports (modules) CAN1, CAN2 or CAN3.
@@ -81,6 +81,8 @@ Description: |
 
   In order to use this block, there must be a `CAN Configure` block in the model.
 
+Help: *desc
+
 Status:
   Tested:
     - Reception of messages with a configured ID.

diff --git a/rpp/blocks/sfunction_cansetup.c b/rpp/blocks/sfunction_cansetup.c
index 3a986efcb39b1a3864e3275406b65fca14fda917..5706fcd319f75c2f89554761b9d5703bd6fd2308 100644 (file)
--- a/rpp/blocks/sfunction_cansetup.c
+++ b/rpp/blocks/sfunction_cansetup.c
@@ -37,13 +37,15 @@ Parameters:
   - { name: "Baud rate for CAN bus port 2 [bps]", type: "uint32", range: "1 – 10000000" }
   - { name: "Baud rate for CAN bus port 3 [bps]", type: "uint32", range: "1 – 10000000" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block configures the CAN bus controllers. Exactly one CAN bus
   configuration block must be in the model if any of the CAN Receive
   or CAN Transmit block is used.
 
+Help: *desc
+
 Status:
   Tested:
     - Configuring CAN1, CAN2 and CAN3

diff --git a/rpp/blocks/sfunction_cantransmit.c b/rpp/blocks/sfunction_cantransmit.c
index 5ba90bd29999cf8d832b57bc153ef2d6bd47f918..1e4f5cc7c73c34ad1b927584f328b15bfd290794 100644 (file)
--- a/rpp/blocks/sfunction_cantransmit.c
+++ b/rpp/blocks/sfunction_cantransmit.c
@@ -40,8 +40,8 @@ Parameters:
   - { name: "Automatic mailbox number", type: "bool"                                }
   - { name: "Mailbox number",           type: "int8"                              }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to send a message to the CAN bus. It can be
   configured for any of the CAN ports (modules) CAN1, CAN2 or CAN3.
@@ -69,6 +69,8 @@ Description: |
 
   In order to use this block, there must be a `CAN Configure` block in the model.
 
+Help: *desc
+
 Status:
   Tested:
     - Transmission of the message with configured ID

diff --git a/rpp/blocks/sfunction_din.c b/rpp/blocks/sfunction_din.c
index 70e50cbac466ee119e2f52a915afb14a537563ef..9669e65743fe92d240c20f061755f9e7d8566d52 100644 (file)
--- a/rpp/blocks/sfunction_din.c
+++ b/rpp/blocks/sfunction_din.c
@@ -40,8 +40,8 @@ Parameters:
   - { name: "Pull",                   type: "Choice from Pull-down or Pull-up" }
   - { name: "Active",                 type: "Choice from Active or Tri-stated" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to read the digital inputs on the RPP board. For pins number 0-7 is not
   relevant and not visible parameter 'Use variable threshold' and only one block for each pin
@@ -53,6 +53,8 @@ Description: |
   flag because of this. In case an errors occurs the return value will always be LOW (0). Because the 
   ErrFlag should never set, once set the following steps will never clear it back.
 
+Help: *desc
+
 Status:
   Tested:
     - Changing the pin.

diff --git a/rpp/blocks/sfunction_dinc.c b/rpp/blocks/sfunction_dinc.c
index f5e8ffd782af89a1a322e60e265c3b87c6d3007a..0b8890a7ca0ad5397f6620e4ccb98834f2d7a393 100644 (file)
--- a/rpp/blocks/sfunction_dinc.c
+++ b/rpp/blocks/sfunction_dinc.c
@@ -36,12 +36,14 @@ Parameters:
   - { name: "Reference voltage for pins 8-11 [0-4095]", type: "uint16" }
   - { name: "Reference voltage for pins 12-15 [0-4095]", type: "uint16" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows one to set reference voltage (threshold) for DIN pins. The block have two parameters,
   one for pins 8 - 11 and the other for pins 12 - 15.
 
+Help: *desc
+
 Status:
   Tested:
     - Changing reference voltage.

diff --git a/rpp/blocks/sfunction_frayconfig.c b/rpp/blocks/sfunction_frayconfig.c
index 032c763732175bc97efe73c305fa22010ade3877..34a59405ea642d9df86428d8b512ae2ac5fe6309 100644 (file)
--- a/rpp/blocks/sfunction_frayconfig.c
+++ b/rpp/blocks/sfunction_frayconfig.c
@@ -88,11 +88,13 @@ Parameters:
   - { name: "syncFramePayloadMultiplexEnabled",  type: "bool"   }
   - { name: "secureBuffers",                     type: "uint8"  }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block ...
 
+Help: *desc
+
 Status:
   Tested:
   Untested:

diff --git a/rpp/blocks/sfunction_frayreceive.c b/rpp/blocks/sfunction_frayreceive.c
index b695a3ff9e00e4447a2fb332874b9bb5b6a2fc48..acb708685f6c26f8497462d98cee41349fca962f 100644 (file)
--- a/rpp/blocks/sfunction_frayreceive.c
+++ b/rpp/blocks/sfunction_frayreceive.c
@@ -45,11 +45,13 @@ Parameters:
   - { name: "singleTransmit", type: "bool" }
   - { name: "slotId", type: "uint32" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block ...
 
+Help: *desc
+
 Status:
   Tested:
   Untested:

diff --git a/rpp/blocks/sfunction_fraysbc.c b/rpp/blocks/sfunction_fraysbc.c
index 79459fb67260d6b253502b94085f15c075b1740e..0ed95f1cc2c3c8390231a9d5164fb9028cb762e9 100644 (file)
--- a/rpp/blocks/sfunction_fraysbc.c
+++ b/rpp/blocks/sfunction_fraysbc.c
@@ -34,11 +34,13 @@ Outputs:
 
 Parameters:
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block ...
 
+Help: *desc
+
 Status:
   Tested:
   Untested:

diff --git a/rpp/blocks/sfunction_fraytransmit.c b/rpp/blocks/sfunction_fraytransmit.c
index e16cd27d90a80e972d70a3b9ad39368120df5737..466616e47d1ad85f18b79d1882c9594b2f2287c5 100644 (file)
--- a/rpp/blocks/sfunction_fraytransmit.c
+++ b/rpp/blocks/sfunction_fraytransmit.c
@@ -43,11 +43,13 @@ Parameters:
   - { name: "singleTransmit", type: "bool" }
   - { name: "slotId", type: "uint32" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block ...
 
+Help: *desc
+
 Status:
   Tested:
   Untested:

diff --git a/rpp/blocks/sfunction_hbr.c b/rpp/blocks/sfunction_hbr.c
index 7e9900dc91e7dba1b8b32d051cb62440decabb5e..8a3bb6fe491fcb1fe57279ee34aac4ee832bb45c 100644 (file)
--- a/rpp/blocks/sfunction_hbr.c
+++ b/rpp/blocks/sfunction_hbr.c
@@ -37,14 +37,16 @@ Outputs:
 
 Parameters:
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to control the H-Bridge on the RPP board. The ErrFlag should raise only if
   `rpp_hbr_control()` returns error. The H-Bridge is initialized with the default frequency 
   (~18kHz). A future improvement could include a parameter to set the frequency. Because the ErrFlag 
   should never set, once set the following steps will never clear it back.
 
+Help: *desc
+
 Status:
   Tested:
     - Compilation and general use.

diff --git a/rpp/blocks/sfunction_irc.c b/rpp/blocks/sfunction_irc.c
index d2f22c2cbb605b8045bc092c06ce79061bba4e3a..63e27f112f05b5df46a70602be7926dc5198d6e3 100644 (file)
--- a/rpp/blocks/sfunction_irc.c
+++ b/rpp/blocks/sfunction_irc.c
@@ -37,14 +37,16 @@ Outputs:
 Parameters:
   - { name: "IRC number [1-2]", type: "uint8" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to read a value of an IRC sensors. Two
   configurations are supported: IRC is connected to pins DIN10 and DIN11
   and/or pins DIN14 and DIN15. The ErrFlag output raises if an error is
   detected, which should normally not happen.
 
+Help: *desc
+
 Status:
   Tested:
     - Compilation and general use.

diff --git a/rpp/blocks/sfunction_lout.c b/rpp/blocks/sfunction_lout.c
index e2338274d864f80b1c11165906d0f426d78558ea..b390b5c1d809ced3b15897ff69149942f44fbfe3 100644 (file)
--- a/rpp/blocks/sfunction_lout.c
+++ b/rpp/blocks/sfunction_lout.c
@@ -37,14 +37,16 @@ Outputs:
 Parameters:
   - { name: "Pin number [1-8]", type: "uint8" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to write to the digital outputs on the RPP board. The ErrFlag should raise if 
   `rpp_lout_set()` or `rpp_lout_update()` returns error. Because the ErrFlag should never set, 
   once set the following steps will never clear it back. `rpp_lout_update()` is called on each 
   block, which is not the most efficient but guaranties consistent behavior.
 
+Help: *desc
+
 Status:
   Tested:
     - Changing the pin.

diff --git a/rpp/blocks/sfunction_mout.c b/rpp/blocks/sfunction_mout.c
index f4194bbf43d5f0dbd91d59480ac576c6c4145aad..5587d4d26ab3ff8413299d8b5fdd25a5a38dd420 100644 (file)
--- a/rpp/blocks/sfunction_mout.c
+++ b/rpp/blocks/sfunction_mout.c
@@ -37,8 +37,8 @@ Outputs:
 Parameters:
   - { name: "Pin number [1-6]", type: "uint8" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to write the power outputs (2A) on the RPP board. The ErrFlag should raise only 
   if `rpp_mout_set()` returns error. Note that `rpp_mout_set()` returns error only if some bad 
@@ -47,6 +47,8 @@ Description: |
   the next step the call will successfully detect the faulty condition and ErrFlag should set. 
   Because the ErrFlag should never set, once set the following steps will never clear it back.
 
+Help: *desc
+
 Status:
   Tested:
     - Changing the pin.

diff --git a/rpp/blocks/sfunction_scic.c b/rpp/blocks/sfunction_scic.c
index 6d8f491deea7200e1624356517edf6ee671f2239..87710666b113e9f430817c63d0645b0c36dadd18 100644 (file)
--- a/rpp/blocks/sfunction_scic.c
+++ b/rpp/blocks/sfunction_scic.c
@@ -35,12 +35,14 @@ Outputs:
 Parameters:
   - { name: "Baud rate", type: "uint32" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to configure the baud rate of the SCI. There should be only one block of this type 
   per model, and this requirement is validated.
 
+Help: *desc
+
 Status:
   Tested:
     - Changing baud rate.

diff --git a/rpp/blocks/sfunction_scip.c b/rpp/blocks/sfunction_scip.c
index b830aee3d897e836f0672b1f5aa7c5e90cea8c90..d6f80e68065bc0c0db7cf675b9abe9249a184b1f 100644 (file)
--- a/rpp/blocks/sfunction_scip.c
+++ b/rpp/blocks/sfunction_scip.c
@@ -37,8 +37,8 @@ Outputs:
 Parameters:
   - { name: "PrintFormat [SETTING]", type: "string" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to print a formatted string to the SCI. The PrintFormat
   string parameters SETTING is used as the format specifier. Note that this value is
@@ -48,6 +48,8 @@ Description: |
   Because of Simulink limitations, it is not posible join diferent types in to one vector.
   So one block can be used only for one type of inputs.
 
+Help: *desc
+
 Status:
   Tested:
     - Sending data.

diff --git a/rpp/blocks/sfunction_scir.c b/rpp/blocks/sfunction_scir.c
index ae7b29af6601d68cc4f4ba5713c5e86afaaf5141..9416540ee9d22259dfc259fa21e8b1a8066ab662 100644 (file)
--- a/rpp/blocks/sfunction_scir.c
+++ b/rpp/blocks/sfunction_scir.c
@@ -36,14 +36,16 @@ Outputs:
 
 Parameters:
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to receive a byte from the SCI. The ErrFlag should raise if `rpp_sci_read_nb()`
   doesn't succeed. The behavior of the ErrFlag is different from others blocks in that this block 
   will set or clear the flag if the call fails of success at each step. Note that this block uses the
   non-blocking call to read the SCI and thus will never cause an overrun.
 
+Help: *desc
+
 Status:
   Tested:
     - Receiving data.

diff --git a/rpp/blocks/sfunction_scis.c b/rpp/blocks/sfunction_scis.c
index b169a10cef327292d4df1b502e2e99371fee93d5..ec978f7814ba932b0789a6a0228d547b3eae6eac 100644 (file)
--- a/rpp/blocks/sfunction_scis.c
+++ b/rpp/blocks/sfunction_scis.c
@@ -36,13 +36,15 @@ Outputs:
 
 Parameters:
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to send a byte to the SCI.
 
   The ErrFlag will be set only if `rpp_sci_write_nb()` returns an error.
 
+Help: *desc
+
 Status:
   Tested:
     - Sending data.

diff --git a/rpp/blocks/sfunction_sdrw.c b/rpp/blocks/sfunction_sdrw.c
index 27a2d151e0c0ec16b28379ada63d1957f4681b73..904f3d5b91715ed1bc76f90a7d6c831955d1f489 100644 (file)
--- a/rpp/blocks/sfunction_sdrw.c
+++ b/rpp/blocks/sfunction_sdrw.c
@@ -38,8 +38,8 @@ Parameters:
   - { name: "Block ID",              type: "uint8"  }
   - { name: "PrintFormat [SETTING]", type: "string" }
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block allows to log a double value to the SD-RAM. User needs to provide a valid PrintFormat 
   string to format and register the double value on the log. The PrintFormat string should include 
@@ -54,6 +54,8 @@ Description: |
   step. The ErrFlag will set if `rpp_sdr_printf()` returns an error (for example out of memory), 
   but will clear back if the next step the call to this function is successful.
 
+Help: *desc
+
 Status:
   Tested:
     - Logging data.

diff --git a/rpp/blocks/sfunction_tror.c b/rpp/blocks/sfunction_tror.c
index fcccfa2a3e02130b73d46fc5c0060c5ac9f8119f..3b473e9778a15da32638aa221c5aa0b7215bcad8 100644 (file)
--- a/rpp/blocks/sfunction_tror.c
+++ b/rpp/blocks/sfunction_tror.c
@@ -33,12 +33,14 @@ Outputs:
 
 Parameters:
 
-# Description is in Markdown mark-up
-Description: |
+# Description and Help is in Markdown mark-up
+Description: &desc |
 
   This block triggers connected simulink function subsystems in case that
   previous loop took more time than simulation time is set.
 
+Help: *desc
+
 Status:
   Tested:
     - Overun detection.