The essence of XMPP (a.k.a Jabber) is specified in two RFCs, 3920 and 3921. Both are solid, reasonably readable documents. For actual implementations though, the current in-progress revisions, named with a "bis" appendix and a counter (like 3920bis-03), are more suitable. Better structure, more examples, more details. They contain all the lessons learned from the XMPP public lists at xmpp.org. But they are still moving targets.

Furthermore, every XMPP server implementation has to conform to another handful of non-trivial RFCs and a dozen of XEPs. It's hard to always know what code is implementing what part of which spec. This gets even more complicated where RFC and -bis contradict each other. How do we know which spec version is used by every developer?

That must have been the situation for Gerolf Seitz, when he was working on Vysper for a short time.

He proposed to annotate the source code with information about the related spec section. These annotations where unmaintained for a while, mostly because you can have only one annotation of the same type per element (class, method). Vysper is implemented following the bis's, but section numbering still changes slightly from revision to revision, which invalidates the annotations. Sometimes you want to link to more than one spec (RFC and RFCbis, bis-01 and bis-03, or differenct sections of the same spec). Now this is mostly resolved, and I am happy again with @SpecCompliant.

What changed?

At first, (not being very much into annotations) I found out how to have more than one @SpecCompliant at the same place:

             
@SpecCompliance(compliant = {
    @SpecCompliant(spec = "RFC3921bis-05", 
                   section = "3.3.3", 
                   status = IN_PROGRESS, 
                   comment = "current impl based hereupon"),
    @SpecCompliant(spec = "RFC3921bis-08", 
                   section = "3.3.3", 
                   status = NOT_STARTED, 
                   comment = "substantial additions from bis-05 
                              not yet taken into account")
})
            

As you can see, comments where added, too.

This gets very helpful. Now, different specs or spec revisions can be annotated side-by-side.

Using a standard JDK tool called apt (hope this link won't stop working for at least the next months) and writing some little glue code, a compliance overview doc can be generated, listing all SpecCompliant annotations in one HTML file. That's great. The table links out to the relevant spec section(s) and to the javadoc where this is implemented. For a snapshot example, see here.

Now it's easy to get an idea about our spec coverage and developers can jump directly to the spec from the relevant class or method.

The only thing we still need now is the power which automagically creates the implementation from the spec. Contributions welcome :-)