1. Style idea for writing code that turns into documentation
- Posted by _tom (admin) Jun 15, 2015
- 1370 views
I was looking at Andreas Wagner's tinEWG and I have been experimenting with a style for writing code that makes it easier, at least for me, to produce documentation.
A sample from tinEWG could look like this:
--** -- returns the state of the widget. -- -- Used for checkbox, radio, and pushbutton widgets. -- -- Returns //True// if the specified ##Checkbox## or ##Radio## button is checked, or if the specified ##pushbutton## is pushed. -- See Also: -- ~| [[Checkbox]] | [[Radio]] | [[Pushbutton]] | public function --> atom : True (!0) if checked, False (0) if not checked IsChecked ( atom handle -- is the handle of the checkbox, radio or pushbutton widget to verify ) atom result result= SendMessage (handle,BM_GETCHECK,Null,Null) if result=BST_CHECKED then return True else return False end if end function
The --** marks the start of a documented subroutine. The subroutine itself would be written in an "expanded" style that can drop into the documentation without any changes--meaning less work ultimately. The --> tells you the return value for a function, each parameter gets a line saying what it does. Because Euphoria is friendly this style has no impact on how the program executes.
With minimal fuss, the documentation now looks like:
IsChecked
returns the state of the widget.
public function --> atom : True (!0) if checked, False (0) if not checked IsChecked ( atom handle -- is the handle of the checkbox, radio or pushbutton widget to verify )
Used for checkbox, radio, and pushbutton widgets.
Returns True if the specified Checkbox or Radio button is checked, or if the specified pushbutton is pushed.
See Also:
| Checkbox | Radio | Pushbutton |
_tom
2. Re: Style idea for writing code that turns into documentation
- Posted by petelomax Jun 15, 2015
- 1336 views
--> atom : True (!0) if checked, False (0) if not checked
That alone would slowly drive me nuts
public function --> atom : True (!0) if checked, False (0) if not checked IsChecked ( atom handle -- is the handle of the checkbox, radio or pushbutton widget to verify )
And having to read code like that even more so. Anyway, would not the following be better final documentation, and just as easy to achieve?
IsChecked(atom handle)
handle is the id of a checkbox, radio or pushbutton widget
Returns True if the specified control is currently checked or depressed.
See Also:
| Checkbox | Radio | Pushbutton |
Pete