Images in code comments

Romain Guy writes in his (excellent) blog about a simple and great idea to improve commenting of source code. Basically all he proposes is a simple way to include images into comments. I would love this, becase especially when programming Swing it can be really helpful to have an image explaining what you currently have to say in 1000 words.

The link:
http://www.jroller.com/page/gfx/20050417#the_future_of_source_code

Of course, the next step would be to have Wiki-like or HTML WYSIWYG editing of comments.

What do you think? Should IDEA push the envelope in this direction?

4 comments
Comment actions Permalink

There have been many talks/requests in the past for ways to better
decorate java code editors contents:
- by adding icons (ex: for properties, for exceptions, for return..),
- by adding frames around elements (method names, inner classes, ..)
- by changing the background colour on limited area (inner classes, ..)
- etc...

, but they never made it: too complex to implement, and lack of support
votes.

This request, on the contrary, should be really easy to implement, in
its simple form at least. I'll vote for it, when you post it into the JIRA.


In the same vein, but a different request: if we could just mark code
areas for display enhancement...
ex:
// $$FRAGILE_CODE.START$$ background=yellow
...
...
// $$FRAGILE_CODE.END$$

that would be great too.


Alain

0
Comment actions Permalink

You see, javadocs are already have a rich formatting syntax: HTML. If I need to include images in my javadocs, I'll do that with tags, and I often use emphatic and strong text in my docs too. And what's better, IDEA already supports the display of rich comments: CTRL+Q on any method, and IDEA will show the fully formatted version of that method's documentation. So, what's left for JetBrains to implement? A WYSIWYG in-place HTML editor, and that doesn't sound like an easy task. On the other hand, there are very few HTML features that are actually useful in a javadoc comment, and it might not be too hard to implement a visual editor for them. From the tip of my tongue: 1) Text styling (, ) 2) Lists (

    ,
    ,
  1. ) 3) Links (]]>
and {@link})

The in-place editor would replace the raw javadoc, and would work mostly by the select-apply idiom: You select a piece of text, right-click it and choose to apply a certain style. Hmm... work is slow today, so I might be able to pull one of those cool mock-up screenshots ;)

0
Comment actions Permalink

Thanks for the Ctrl-Q hint, I did not know about that, but this seems to be more a preview feature intended to check what the API docs will look like when others read the later. What I am looking for is to have each comment permanently replaced by the formatted comment, maybe with a little button to toggle views.

The html formatting syntax of javadocs should be enough. Technical implementation should not be that difficult (I happen to be working with the Swing text package at the moment). The line views of the comments only need to be replaced by one HTML document view.

And of course we IDEA users are never satisfied, so when showing the styled comment, there should be a possibility to show/hide a toolbar for simple text formatting (bold, italic, underline, font size, font color, insert image, etc).

0
Comment actions Permalink

When I had this idea of showing picture in comments, I also thought about providing rich formatting, and thus using HTML from within comments.

Yet, I don't think there is much added value in using rich text for comments. Most of the time, clearly formatted comments are enough. Now, displaying pictures is a bit different since they really are useulf and add information to the text, they don't just enhance presentation (even it that would be cool anyway).

Using a simple formatting form, like enclosing the filename between two sharps, allows to quickly add a picture but also to create highly readable comments. (X)HTML is great but it adds a lot of clutter to comments. I wanted to get something easy to read/use even in inappopriate editors. The solution I propose is far from perfect but it is "good enough" for a demo.

Last but not least, this is really very very easy to implement! It took me a one hour to write the demo. Given I had to write a Java syntax coloring algorithm, it is not much.

Now, more work would be needed to enhance rendering like adding comments as a left border of the picture would be great if there is no non-whitespace character before the picture. We could also imagine drawing border around the lien containing the picture, etc. Or maybe drawing the picture within the nearest blank space, with an arrow connecting the comment and the picture. Editing process would also require some work but it shouldn't be too hard either.

0

Please sign in to leave a comment.