question about doc comments in Eclipse

On Mon, Nov 30, 2009 at 9:02 AM, martin odersky wrote:
> I have a question: How does Eclipse render doc comments? Does it go
> directly in the source text, or work off the
> comments map in Global? Or does it do something else entirely? I am
> asking because we plan to move to optional wiki syntax for internal
> comments. It would be nice if Eclipse could render that correctly.

It extracts them from source text (it does this uniformly between
Scala and Java, ie. hovering over a reference to a Scala element in
Java source uses the same mechanism).

If you can provide me with a function (ideally with minimal
dependencies, ie. no dependencies on Global) taking the contents of a
doc comment as a String argument, which can detect wiki-marked up
Scaladoc and convert it to he equivalent Javadoc syntax then I should
be able to insert the conversion on the fly and Eclipse won't see any
difference between the two formats.

Cheers,

Miles

On Mon, Nov 30, 2009 at 11:46 AM, Miles Sabin wrote:
> On Mon, Nov 30, 2009 at 9:02 AM, martin odersky wrote:
>> I have a question: How does Eclipse render doc comments? Does it go
>> directly in the source text, or work off the
>> comments map in Global? Or does it do something else entirely? I am
>> asking because we plan to move to optional wiki syntax for internal
>> comments. It would be nice if Eclipse could render that correctly.
>
> It extracts them from source text (it does this uniformly between
> Scala and Java, ie. hovering over a reference to a Scala element in
> Java source uses the same mechanism).
>
> If you can provide me with a function (ideally with minimal
> dependencies, ie. no dependencies on Global) taking the contents of a
> doc comment as a String argument, which can detect wiki-marked up
> Scaladoc and convert it to he equivalent Javadoc syntax then I should
> be able to insert the conversion on the fly and Eclipse won't see any
> difference between the two formats.
>
I can do that, but it will have dependencies on Global. The problem is that
I have to expand variables which are retrieved by following the
ownerchain of a Symbol.

Cheers

On Mon, Nov 30, 2009 at 10:54 AM, martin odersky wrote:
> On Mon, Nov 30, 2009 at 11:46 AM, Miles Sabin wrote:
>> If you can provide me with a function (ideally with minimal
>> dependencies, ie. no dependencies on Global) taking the contents of a
>> doc comment as a String argument, which can detect wiki-marked up
>> Scaladoc and convert it to he equivalent Javadoc syntax then I should
>> be able to insert the conversion on the fly and Eclipse won't see any
>> difference between the two formats.
>>
> I can do that, but it will have dependencies on Global. The problem is that
> I have to expand variables which are retrieved by following the
> ownerchain of a Symbol.

Could you explain this for me? Why does mapping syntax require
variable expansion (which sounds semantic to me)?

An example would be very helpful.

Cheers,

Miles

On Mon, Nov 30, 2009 at 12:18 PM, Miles Sabin wrote:
> On Mon, Nov 30, 2009 at 10:54 AM, martin odersky wrote:
>> On Mon, Nov 30, 2009 at 11:46 AM, Miles Sabin wrote:
>>> If you can provide me with a function (ideally with minimal
>>> dependencies, ie. no dependencies on Global) taking the contents of a
>>> doc comment as a String argument, which can detect wiki-marked up
>>> Scaladoc and convert it to he equivalent Javadoc syntax then I should
>>> be able to insert the conversion on the fly and Eclipse won't see any
>>> difference between the two formats.
>>>
>> I can do that, but it will have dependencies on Global. The problem is that
>> I have to expand variables which are retrieved by following the
>> ownerchain of a Symbol.
>
> Could you explain this for me? Why does mapping syntax require
> variable expansion (which sounds semantic to me)?
>
We need to define variables in doc comments to make sense of inherited
comments better. have a look at the doc comments of class
scala.collection.TraversableLike and of scala.collection.List that I
just checked in (r19935). TraversableLike defines a variable $coll
which is initally bound to "traversable collection" and which is
specialized to "list" in class "List". That way, all doc commentsd
read list when seen from class list. That's just a simple example,
there are a lot of others like this.

Cheers

On Mon, Nov 30, 2009 at 12:50 PM, martin odersky wrote:
> On Mon, Nov 30, 2009 at 12:18 PM, Miles Sabin wrote:
>> Could you explain this for me? Why does mapping syntax require
>> variable expansion (which sounds semantic to me)?
>>
> We need to define variables in doc comments to make sense of inherited
> comments better. have a look at the doc comments of class
> scala.collection.TraversableLike and of scala.collection.List that I
> just checked in (r19935). TraversableLike defines a variable $coll
> which is initally bound to "traversable collection" and which is
> specialized to "list" in class "List". That way, all doc commentsd
> read list when seen from class list. That's just a simple example,
> there are a lot of others like this.

OK, that makes sense.

One request: it would be great if there were sensible fallback
behaviour if any of the semantic information which drives these
substitutions is unavailable (eg. because of compilation errors).

One option might be to enforce that every substitution specifies a
default to be used if the expansion fails, eg. ${coll:traversable
collection}.

Cheers,

Miles

On Mon, Nov 30, 2009 at 2:21 PM, Miles Sabin wrote:
> On Mon, Nov 30, 2009 at 12:50 PM, martin odersky wrote:
>> On Mon, Nov 30, 2009 at 12:18 PM, Miles Sabin wrote:
>>> Could you explain this for me? Why does mapping syntax require
>>> variable expansion (which sounds semantic to me)?
>>>
>> We need to define variables in doc comments to make sense of inherited
>> comments better. have a look at the doc comments of class
>> scala.collection.TraversableLike and of scala.collection.List that I
>> just checked in (r19935). TraversableLike defines a variable $coll
>> which is initally bound to "traversable collection" and which is
>> specialized to "list" in class "List". That way, all doc commentsd
>> read list when seen from class list. That's just a simple example,
>> there are a lot of others like this.
>
> OK, that makes sense.
>
> One request: it would be great if there were sensible fallback
> behaviour if any of the semantic information which drives these
> substitutions is unavailable (eg. because of compilation errors).
>
> 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. 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 $?)

Cheers

Hello Miles.

Martin's answer is concerned with the expansion of documentation variables and dealing with simplified definitions. This is part of the problem, and Martin is answering it.

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.

Cheers,
Gilles.

> If you can provide me with a function (ideally with minimal
> dependencies, ie. no dependencies on Global) taking the contents of a
> doc comment as a String argument, which can detect wiki-marked up
> Scaladoc and convert it to he equivalent Javadoc syntax then I should
> be able to insert the conversion on the fly and Eclipse won't see any
> difference between the two formats.