[Gambas-user] New Gambas markup syntax

[Benoît Minisini]

Le 03/09/2012 09:21, Bruce a écrit :
> Last one!  [Today :-)]
>
> Given that
> a) a help comment appended to a method declaration line overrides all
> the wonderful help text I have composed above it, and

This is by design. Either you put a comment on the same line of the 
symbol (at the end of course), or just before.

> b) the code folder hides all the "above the line" help if the prior
> method is collapsed.

Yes, the code folder does not care with help. I don't think I can fix 
that at the moment.

>
> I rather see that the help was based on the "below the line" approach.
>
> For example:
>
> Public Function Mash(param 1 as Thing) As Mess  '' This wonderful
> '' method takes a single parameter !!param1!! and mashes it into
> '' an incomprehensible !!Mess!!
> '' + !!param1!! is the [Thing][] you want mashed
> '' ##Usage
> '' Use of this method is not recommended for persons under 18 years old.
> ''     Dim MyMess as Mess
> ''     MyMess = Mash("Some unsuspecting string")
>
>    Dim tmpmuck as new Mess
>
>    tmpmuck=Whack(param1)
>    tmpmuck=Chop(tmpmuck)
>    tmpmuck=Mangle(tmpmuck)
>    Return WhatsLeftOf(tmpmuck)
>
> End

I think it's better to have the help *before*, especially with code 
folding hiding everything inside the function.

Regards,

-- 
Benoît Minisini