LUA API - format in C++ code

[JimB40]

if we insist on using GitBook only effect will be miserable considering C++ devs reclutancy to make decent documentation.
Moreover if API func information is in C++ comment form we or you @pfeerick can easily check if it was updated during PR accept process

Examples to discuss

Simple - lcd.clear

-- @name lcd.clear
--
-- @description Clears the LCD screen optionaly filling it with selected color
-- 
-- @syntax lcd.clear( [color] )
--
-- @arg color optional integer [colorFlag] 
-- @argdesc see [Drawing Flags]
--
-- @return none
-- 
-- @notes This function works only in stand-alone and telemetry & widget scripts. See [script types]
--
-- @target [BW]
-- @target [GS]
-- @target [COLOR]
-- 
-- @apistat 2.3.0 Introduced

More arguments - lcd.drawBitmap

-- @name lcd.drawBitmap
--
-- @description Displays prevoiusly loaded bitmap at (x,y) and optionally scales it. 
--
-- @syntax  lcd.drawBitmap( bitmap, x, y [, scale] )
--
-- @arg bitmap required bitmapPointer 
-- @argdesc stored in variable pointer to a bitmap previously opened with [Bitmap.open]
-- @arg x required integer
-- @argdesc top coordinate
-- @arg y required integer
-- @argdesc left coordinate
-- @arg scale optioonal integer (0-100)
-- @argdesc scale in percent ie. 50 divides size by two, 100 displays bitmap in original size, 200 doubles size.
--
-- @return none
-- 
-- @note Omitting scale draws image in 1:1 scale and is faster than specifying 100 for scale parameter.
-- 
-- @target [COLOR]
-- 
-- @apistat 2.3.0 Introduced
-- @apistat 2.8.0 Added scale prameter

Alternate syntax - lcd.RGB

-- @name lcd.RGB
--
-- @description Returns [colorFlag] in RGB565 format that can be used with lcd draw functions.
-- 
-- @syntax lcd.clear( r,g,b )
-- @arg r required integer  
-- @argdesc number between 0 (0x00) and 255 (0xFF) that expresses amount of red in the color
-- @arg g required integer  
-- @argdesc number between 0 (0x00) and 255 (0xFF) that expresses te amount of green in the color
-- @arg b required integer
-- @argdesc number between 0 (0x00) and 255 (0xFF) that expresses te amount of blue in the color
--
-- @syntax lcd.clear( rgb )
-- @arg rgb required integer
-- @argdesc number between 0 (0x00) and 16777215 (0xFFFFFF) that expresses the RGB value (0xFF0000=RED, 0x00FF00=GREEN, 0x0000FF=BLUE)
--
-- @return colorFlag integer
-- @returndesc See [Drawing Flags] 
-- 
-- @notes
--
-- @target [COLOR]
-- 
-- @apistat 2.3.0 Introduced

[pfeerick]

In starting to use this for #5181, two points

• should be using CPP style multi-line comment block tags -/* */
• how to specify which section the documented command belongs under? As this looks to be near enough information we can have a stab at a new processor to take a comment to a markdown doc automatically for easier insertion.

[philmoz]

@JimB40 Is there a 2.11 reference guide? The LVGL API documentation needs to go somewhere.

[pfeerick]

Yes, as is being previewed at https://luadoc.edgetx.org/v/next-snapshot. I'll send you an invite to gitbook for it, as it is being worked on directly on gitbook for now.

[philmoz]

@JimB40 I've started adding the LVGL API documentation to Gitbook. When you have time your feedback would be appreciated.