1. Style idea for writing code that turns into documentation

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

new topic     » topic index » view message » categorize

2. Re: Style idea for writing code that turns into documentation

_tom said...
      --> atom : True (!0) if checked, False (0) if not checked 

That alone would slowly drive me nuts

_tom said...
    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

new topic     » goto parent     » topic index » view message » categorize

Search



Quick Links

User menu

Not signed in.

Misc Menu