search

lampepfl / dotty-feature-requests

Historical feature requests. Please create new feature requests at https://github.com/lampepfl/dotty/discussions/new?category=feature-requests
31 stars 2 forks source link

Better Scaladoc format for structured comments #273

Closed ckipp01 closed 2 years ago

ckipp01 commented 2 years ago

So this might be a tricky one, but it'd be great to retain the structure of a comment in the Scaladocs. A good example of this can be found if you look at the comment at the top of TastyFormat https://github.com/lampepfl/dotty/blob/master/tasty/src/dotty/tools/tasty/TastyFormat.scala#L3-L263. There is a ton of great info in here, and I just checked out the Scaladocs hoping to read through it and all of the structure is obliterated.

https://scala-lang.org/api/3.x/dotty/tools/tasty/TastyFormat$.html

EDIT: Actually I think this is mainly due to the comment type. If it was done similar to https://scala-lang.org/api/3.x/scala/quoted/Quotes$reflectModule.html and put in a different style of comment to match that it'd appear much better. I'll just change this instead.

smarter commented 2 years ago

I think the easy fix here is to wrap any comment where structure is important (diagrams, the example above, etc) in a code block (``` ... ```), I would accept a PR making that change to TastyFormat.

ckipp01 commented 2 years ago

I think the easy fix here is to wrap any comment where structure is important (diagrams, the example above, etc) in a code block (``` ... ```), I would accept a PR making that change to TastyFormat.

Sounds good, opened https://github.com/lampepfl/dotty/pull/14192