OpenEuphoria

Style idea for writing code that turns into documentation

• Posted by _tom (admin) Jun 15, 2015
• 1371 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 |