Re: Re: question about doc comments in Eclipse

On Mon, Nov 30, 2009 at 1:40 PM, martin odersky wrote:
> On Mon, Nov 30, 2009 at 2:36 PM, Miles Sabin wrote:
>> Dropping the initial $ and using the variable name is definitely
>> better than failing. Would you object to also supporting the default
>> syntax I suggested as well?
>>
> One could do it, but I fear it would make comment writing more strenuous.

I agree it should be optional ...

> Note that it's not the superclass that's necessary but the enclosing
> class. If you can't identify the enclosing class, I believe nested
> definitions and their comments would not be of much use to you anyway.

OK, understood.

Cheers,

Miles

On Mon, Nov 30, 2009 at 2:36 PM, Miles Sabin wrote:
> On Mon, Nov 30, 2009 at 1:29 PM, martin odersky wrote:
>> On Mon, Nov 30, 2009 at 2:21 PM, Miles Sabin wrote:
>>> One option might be to enforce that every substitution specifies a
>>> default to be used if the expansion fails, eg. ${coll:traversable
>>> collection}.
>>
>> In a sense it does that already. Every defined variable immediately
>> gets a value, which can be overridden in subclasses.
>
> Yes, but that only works where sources are sufficiently coherent that
> the superclass can be identified and parsed sufficiently to extract
> the default. It would be a shame to completely lose Javadoc's property
> that something sensible can be done with the contents of a doc comment
> irrespective of how broken it's context is.
>
>> I hope that's good enough; if not we can think of alternatives to make
>> it more robust (maybe just take the variable name without leading $?)
>
> Dropping the initial $ and using the variable name is definitely
> better than failing. Would you object to also supporting the default
> syntax I suggested as well?
>
One could do it, but I fear it would make comment writing more strenuous.
Note that it's not the superclass that's necessary but the enclosing
class. If you can't identify the enclosing class, I believe nested
definitions and their comments would not be of much use to you anyway.

Cheers

On Mon, Nov 30, 2009 at 1:44 PM, Gilles Dubochet
wrote:
> Concerning parsing the wiki syntax into something that Eclipse can deal
> with, here is what you have to do.
>
> - use the "parse" method in nsc.doc.model.comment.CommentFactory
> to obtain a Comment instance, i.e. an abstract representation of the
> wikified comment.
> - use the "commentToHtml" method in nsc.doc.html.HtmlPage to transform
> the comment's body (and those tags you are interested in) into HTML.
>
> If it isn't practical to instantiate a dummy HtmlPage to HTMLify the
> comments, I can outsource that part of HtmlPage's logic into a helper class.

I really need the conversion to be to Javadoc for this to fit into
Eclipse's model. HTML would give a prettily formatted hover, but it
would lack all of the navigational features that Javadoc hovers
currently have (if you haven't tried this in Eclipse recently, please
do).

So what I really need is a helper class which has a,

scaladocToJavadoc(compiler : Global, content : String) : String

method which maps the wiki markup to the nearest eqivalent Javadoc construct.

Cheers,

Miles

--
Miles Sabin
tel: +44 (0)7813 944 528
skype: milessabin
http://www.chuusai.com/
http://twitter.com/milessabin