search

Aerilius / sketchup-console-plus

A better Ruby Console and IDE for integrated development in SketchUp.
MIT License
42 stars 16 forks source link

Some core/stdlib documentation has bad formatting #4

Closed Aerilius closed 7 years ago

Aerilius commented 7 years ago

The autocompleter doc tooltip displays poorly formatted text for RDoc extracted from C source code. For example there are no line breaks and formating syntax like + _ * is visible. Parameters seem not to be extracted into parameter tags.

Are these cases where the doc is written too much human-style that yardoc cannot extract parameters? Is there a yardoc method that returns html-formatted description? Should we otherwise try to convert RDoc formatting into html (RDoc stdlib, markdown javascript)? Do we need to convert \n into <br/>?

Test case:

Type in the console or editor Kernel.block_given?

MSP-Greg commented 7 years ago

@Aerilius

Are these cases where the doc is written too much human-style that yardoc cannot extract parameters?

First of all, re rdoc based doc, its been a while since I looked at rdoc, so I don't recall how well it can doc parameter or return types/descriptions. Regardless, even it it can, the comments in Ruby don't do so. Examples at my doc site here.

Is there a yardoc method that returns html-formatted description? Should we otherwise try to convert RDoc formatting into html (RDoc stdlib, markdown javascript)? Do we need to convert \n into \<br\/>?

I'll take a look. I think so, but don't recall how.

I haven't downloaded the plug-in or forked the repo yet. FYI, I've got Ruby 2.3 hacked into SU 2017, I'll try the code there. Right now I'm spending most of my 'OSS time' trying to get better windows support for Ruby...

Aerilius commented 7 years ago

The method block_given? did not show documentation in all contexts (e.g. when directly called at Kernel) because on Kernel it is used as class method (Kernel.block_given?) but it is documented as. instance method (Kernel#block_given?). When I added lookup in included modules in commit 5c2bbe31e60969793a1a040315ef92a530f1e961 it seems this was also fixed.

For RDoc I decided to detect and replace markup in the description text with a simple regexp (instead of requiring additional libraries). fc419a31387c142bf01e5e6a7e53d938f93c21f5

MSP-Greg commented 7 years ago

I guess I had forgotten about that. Notice the difference between the Kernel method lists of rubydoc.info and msp-greg.github.io...

Glad you got it sorted out. Thanks,