- About Scala
- Documentation
- Code Examples
- Software
- Scala Developers
Questions on scaladoc internals
Sat, 2011-02-19, 22:44
Sending this to both internals and Gilles in hopes that I'll be able to get answers in time to do more work this weekend. My life is filled with such excitement :-)
I'm currently working on adding inheritance graphs to scaladoc output. A few questions:
1) I'm not getting edges for direct inheritance. First, here's the code I'm testing scaladoc on, to generate graphs:
package com.animal
/** Animals. */
class Animal;
/** Dwell on water/land. */
trait Amphibious;
/** Just for testing. */
object Frog;
/** Sometimes green. */
class Frog extends Animal with Amphibious;
/** It's not easy being green. */
class Kermit extends Frog;
It appears that when scaladoc runs on this example, the method 'inheritedFrom' on 'DocTemplateEntity' instances is always returning an empty list, so I can't draw in edges for direct superclasses. On the other hand, the 'subClasses' and 'linearTemplates' on 'DocEntityTemplate' instances do return nonempty list.
2) The 'DocTemplateEntity.subClasses' method appears to return all subclasses, not just direct subclasses. What is the preferred way to find direct subclasses of a DocTemplateEntity?
3) Is there a site that contains scaladoc docs for the compiler internals _and_ includes links to source? I'm currently using http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/... , but it does not seem to contain source links. Unfortunately, I can't build 'docscomp' on my current machine due to memory limitations, so I can't do a custom docs build with source links enabled. (Not without ant hacking that is beyond my current abilities, anyway.) This will be rectified once Apple comes out with a new lineup :-), but in the meantime it would be nice to be able to more easily browse source.
Thanks,
Ken
I'm currently working on adding inheritance graphs to scaladoc output. A few questions:
1) I'm not getting edges for direct inheritance. First, here's the code I'm testing scaladoc on, to generate graphs:
package com.animal
/** Animals. */
class Animal;
/** Dwell on water/land. */
trait Amphibious;
/** Just for testing. */
object Frog;
/** Sometimes green. */
class Frog extends Animal with Amphibious;
/** It's not easy being green. */
class Kermit extends Frog;
It appears that when scaladoc runs on this example, the method 'inheritedFrom' on 'DocTemplateEntity' instances is always returning an empty list, so I can't draw in edges for direct superclasses. On the other hand, the 'subClasses' and 'linearTemplates' on 'DocEntityTemplate' instances do return nonempty list.
2) The 'DocTemplateEntity.subClasses' method appears to return all subclasses, not just direct subclasses. What is the preferred way to find direct subclasses of a DocTemplateEntity?
3) Is there a site that contains scaladoc docs for the compiler internals _and_ includes links to source? I'm currently using http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/... , but it does not seem to contain source links. Unfortunately, I can't build 'docscomp' on my current machine due to memory limitations, so I can't do a custom docs build with source links enabled. (Not without ant hacking that is beyond my current abilities, anyway.) This will be rectified once Apple comes out with a new lineup :-), but in the meantime it would be nice to be able to more easily browse source.
Thanks,
Ken
1) `inheritedFrom` is not the right method here: it returns the class from which a member is inherited. `linearizationTemplates` is probably the method you want. You can find a definition of what linearization is in the Scala reference. This does not return only direct superclasses, but all of a class' ancestors. By obtaining the linearization for all ancestors, it should be possible to recreate the whole structure. Alternatively, feel free to extend the Scaladoc model with a method to access only direct super classes. Let me know if you need help with that.
Also, I am right now improving the documenting of the model to make it clear what each method does. I hope to commit the additional comments tomorrow.
2) Like above.
3) I tried the nightly documentation and found links to source. Note however that they are not visible by default: you must click on the class signature to have access to the link (along with other information about the class).
Cheers,Gilles.