API diff docs

[FroMage]

Add a new Ceylon CLI plugin to generate an HTML diff of two versions of a single module.

Output should be similar to ceylon doc, but show added/removed/changed packages, types, methods, values.

This means that it will likely be an extension of the ceylondoc tool, because we want to reuse its rendering capability.

For a Java example, see http://javadiff.sourceforge.net/jdiff/reports/j2se142_j2se150b1/changes.html

[SanjayJosh]

Hello developer , I was given the link to the API diff issue on the mailing list . So ,the API difference as seen for the two java versions have only intel on the number of extra packages. I feel we might need a more visually pleasant page for ours.

[FroMage]

Well, no it shows new packages, removed packages and changed packages. And for each changed package it does the same for types. And for each changed types it does the same for members.

Naturally it would have to look better, it has to look as good as ceylondoc does.

[SanjayJosh]

Oh , I see. Thank you for the insight . So ,how do we go about moving ahead with it ?

[FroMage]

Well, if you want to size the issue and get a feel for it you can always try to check out the code, make a modification, test your change and see how you would attack the issue.

[SanjayJosh]

From what I understood of the issue , we need a sub command instruction in ceylon to show the difference between the two versions. I have set up the ceylon tool in my system . What next ? Can you help me get started with dealing the issue ?

[FroMage]

@thradec might have another opinion, but I think the easiest would be to add a diff mode to CeylonDocTool which would typecheck two modules instead of one and produce a diff rather than normal output.

The problem of course is going to be how we get two versions of the source files? ATM ceylondoc works on the current source folders, of which there can only be one version. It mostly uses the model and not the AST, except for:

• parameter assertions
• constant values
• doc links?
• annotations?

It may be possible to tweak it so that it works on binaries and then we don't require typechecking at all to produce the docs, but it's also possible that we get the "other version" via the .src artifact from Herd, unzip it in a temporary folder and do a second typechecking for it, then compare the models and trees.

WDYT @thradec ?

[thradec]

I would rather see it as separate tool/sub-command, but of course reuse as much code as possible.

The advantage comparing binaries would be, that one could make diff of 3rd party library even without source code.

[SanjayJosh]

@thradec
Umm , could you help me as to get started with this ? I am willing to take this up as a project.

[thradec]

First step is to have working development environment, as described here [1]. Then look how ceylondoc [2] works, there are tests [3] which can help you to play with it. The most interesting will probably be to figure out how to load new and old version into model.

[1] http://ceylon-lang.org/code/contribute/
[2] https://github.com/ceylon/ceylon/blob/master/compiler-java/src/com/redhat/ceylon/ceylondoc/CeylonDocTool.java
[3] https://github.com/ceylon/ceylon/blob/master/compiler-java/test/ceylondoc/com/redhat/ceylon/ceylondoc/test/CeylonDocToolTests.java

[xkr47]

@SanjayJosh any progress?

[SanjayJosh]

@xkr47
Sir , I am extremely sorry but I had my projects and university exams . If need be , I am willing to work on this now .