Duncan Gibson wrote:
> I'm also not keen on left markers in multiline comments:
>
> /**
> * \brief The one-liner
> *
> * The detailed description here,
> * on more than one line.
> * \param x
> * \return y
> */
>
> because it's too much faffing about when you need to reformat,
> and I reformat to keep it readable in the editor and avoid lots
> of raggedy short and overly-long text lines.
> I would prefer that we all agree to omit the left markers:
>
> /**
> \brief The one-liner
>
> The detailed description here,
> on more than one line.
> \param x
> \return y
> */
Yes, the practicality for paragraph formatting does make sense.
Though to me, the visual confusion factor is a big issue too,
esp for multiline comments around one liner methods; pretty hard
to tell where a comment stops/starts, and it can be really hard
to find the line of code you're looking for.
Turning on folding in the editor helps with that, but without
that feature, it seems pretty hard to read. eg. for printouts.
For the docs I'm writing for Fl_Browser, I'm following the format
that's already there, without the stars.
Seems kinda important to achieve consensus on this if possible.
_______________________________________________
fltk-dev mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-dev
