Formatting of documentation in source assistant

Hi,

I use Wing IDE 2.1.4-2 on Windows. As provided by default, I
always have
the source assistant open in a narrow window, because this
is very
useful for looking up documentation. However, the formatting
of the doc
comment in the source assistant is less than optimal. E.g.,
when I
formatted a comment like this:

def createFooFromBar(bar):
    """
    This function creates a foo from a bar instance.
    If foo is not valid, a stock bar object will instead
    be returned. This function may throw a
    NoBarAvailableException if the maximum number
    of bars have been exceeded in the system.
    """"
    ... code follows here ...

It shows up in the source assistant like this:

Symbol: createFooFromBar
Likely type: function
mymodule.createFooFromBar(bar)
    This function creates a foo from a bar
instance.
    If foo is not valid, a stock bar object
will instead
    be returned. This function may
throw a
    NoBarAvailableException if the
maximum number
    of bars have been exceeded in the
system.

Needless to say, this wastes space and looks very ugly. I'd
prefer if
Wing would understand that the whole docstring is indented
and would
therefore remove the indentation prior to displaying it in
source
assistant. Also, it would save space if Wing would just
ignore the
newlines in paragraphs and format text continuously until it
finds a
blank line. Further, it would be absolutely great, if Wing
would
understand epydoc comments (param, type
etc.) and format them
accordingly, but I'm dreaming now ;)


Markus

_________________________________________________
Wing IDE users list
http://wingware.com
/lists/wingide

Markus Meyer wrote:
> I use Wing IDE 2.1.4-2 on Windows. As provided by
default, I always have
> the source assistant open in a narrow window, because
this is very
> useful for looking up documentation. However, the
formatting of the doc
> comment in the source assistant is less than optimal.
E.g., when I
> formatted a comment like this:
...
> Needless to say, this wastes space and looks very ugly.
I'd prefer if
> Wing would understand that the whole docstring is
indented and would
> therefore remove the indentation prior to displaying it
in source
> assistant. Also, it would save space if Wing would just
ignore the
> newlines in paragraphs and format text continuously
until it finds a
> blank line. Further, it would be absolutely great, if
Wing would
> understand epydoc comments (param, type
etc.) and format them
> accordingly, but I'm dreaming now ;)

If you right click on the source assistant you can turn off
wrapping
of lines.  The wrapping is being done by the widget, which
of course
has no idea what it's doing and doesn't support a
wrap-to-indent
mode.  We should probably just not indent docstrings to
avoid this
issue.

-- 

Stephan Deibel
Wingware | Python IDE
Advancing Software Development

www.wingware.com

_________________________________________________
Wing IDE users list
http://wingware.com
/lists/wingide

Wingware Support schrieb:
> If you right click on the source assistant you can turn
off wrapping
> of lines.  The wrapping is being done by the widget,
which of course
> has no idea what it's doing and doesn't support a
wrap-to-indent
> mode.  We should probably just not indent docstrings to
avoid this
> issue.
Thanks for the tip! Unfortunately, this will hide part of
the text which
is even worse. What about providing two modes:

* Do not wrap lines: Displays docstrings as-is, but without
the fixed
indent for the whole docstring (makes more room for the
actual text

* Wrap lines: Ignores all indents and new lines and displays
doc strings
as paragraphs of text which are separated by a blank line
(i.e. the way
HTML and Latex treat text).

Additionally, there could be some form of "smart
detection" of paragraph
type. E.g., paragraphs which are evidently pre-formatted
(have
table-like layout like lists of parameters or paragraphs
with keywords
like "param") would not be auto-wrapped.


Markus


_________________________________________________
Wing IDE users list
http://wingware.com
/lists/wingide

Markus Meyer wrote:
> Wingware Support schrieb:
>> If you right click on the source assistant you can
turn off wrapping
>> of lines.  The wrapping is being done by the
widget, which of course
>> has no idea what it's doing and doesn't support a
wrap-to-indent
>> mode.  We should probably just not indent
docstrings to avoid this
>> issue.
> Thanks for the tip! Unfortunately, this will hide part
of the text which
> is even worse. What about providing two modes:
> 
> * Do not wrap lines: Displays docstrings as-is, but
without the fixed
> indent for the whole docstring (makes more room for the
actual text
> 
> * Wrap lines: Ignores all indents and new lines and
displays doc strings
> as paragraphs of text which are separated by a blank
line (i.e. the way
> HTML and Latex treat text).

I've just implemented basically this for Wing 3.0, with some
attempted
smartness about indented things which usually shouldn't be
wrapped.  I'm
sure it'll need some refinement...

> Additionally, there could be some form of "smart
detection" of paragraph
> type. E.g., paragraphs which are evidently
pre-formatted (have
> table-like layout like lists of parameters or
paragraphs with keywords
> like "param") would not be auto-wrapped.

Yes, there's more we can do here.  I expect both for the
general case
and for doctests and similar.

-- 

Stephan Deibel
Wingware | Python IDE
Advancing Software Development

www.wingware.com

_________________________________________________
Wing IDE users list
http://wingware.com
/lists/wingide

Wingware Support schrieb:
> I've just implemented basically this for Wing 3.0, with
some attempted
> smartness about indented things which usually shouldn't
be wrapped.  I'm
> sure it'll need some refinement...
Awesome! Looking forward to 3.0...


Markus

_________________________________________________
Wing IDE users list
http://wingware.com
/lists/wingide