The sole purpose of this entry is get my head around something that has been laying there rotting for quite a while now, and it's about time I get rid of it. I just haven't figured out how to do it yet. So, this is a note to self. Not only reminding me to make some changes (hurry up man!), but also to explain myself what the situation is a like right now, and how I feel I could get rid of it.

First of all, what is a CodecDescriptor. A CodecDescriptor is an interface. It's the interface that needs to be implemented by all Codecs. That is, all Codecs need to be able to return an implementation. It may be implemented by the Codec itself, but it might also be implemented by something else, outside of the codec.

Now, why do we even have an interface like that? The answer is simple. A Codec needs to be able to describe itself. This is just because of the way Preon works. If you construct a Codec for a certain type of data structure, then you essentially create a Codec that delegates to other Codecs, until you hit some of the elementary types defined by the framework. One of the ambitions of Preon is to have something that prevents you from having to maintain documentation on the encoding format. That documentation is generated by the Codecs themselves. They describe themselves, and - if they depend on other Codecs for realizing part of the work - they will delegate generation of documentation to other Codecs.

This approach has been the subject of quite some debate in the past. People argued that using something like a template language would have been good enough. I doubt it.

• First of all, the inner workings of a particular type of Codec might be quite involved. Externalizing the bits responsible for generating documentation would break the encapsulation big time. Logic that is closely related is now spread across two different places.
  
• Second, the Codec will often depend on a number of parameters. For instance, the Codec decoding numeric values requires to have the number of bits set, the byte order, the target data type, etc. All of that is also required for the documentation. Consequently, the template would require access to all of this data, and therefore the Codec would need to publically expose all of this, again breaking the encapsulation.
  
• So you don't want to loose encapsulation, but you do want polymorfism. Whenever a Codec of lists needs to document itself, it needs the ability to say something about the type of elements it's decoding. In terms of Preon, that's just another Codec. When the Codec of lists is documenting itself, it should be able to just ask the element Codec to state something about itself, without being required to understand what that Codec is actually doing. (If you break that restriction, you are going to end up with a kazillion marker interfaces, and a lot of additional code in the Codec of lists.) So, if polymorfism is what you want, the object oriented approach makes a lot of sense.
• In many cases, you would render things differently in a different context. In fact, one way of rendering might be ok in one context, but totally ridiculous in another context. If would for instance make perfect sense to generate a list item in a list, but it would be ridiculous to generate a list item in an image. With all of this, compile time checks come in handy. Not a strong case for template languages.

Now, as you may have noticed, I've drifted away from the question why a Codec needs a separate CodecDescriptor. After all, if they share so much in common - as I argue above - then why not have it al included in one class? In all honesty, I am not sure if I will be able to answer this question. The only thing I can say for sure is that the CodecDescriptor interface has had a comletely different lifecycle than the Codec so far. In many cases, if I didn't care about the actual description yet, I had the Codec return a general purpose Codec descriptor. Maybe not all that sensible, but it allowed me to continue on the important bits, without focusing too much on continuosly implementing boilerplate code.

Anyhow, enough about that. Let's take a look at the actual interface itself. This is it:

public interface CodecDescriptor {
    <T> void writeReference(ParaContents<T> contents);
    String getLabel();
    <T, V extends ParaContents<T>> V putOneLiner(V para);
    boolean hasFullDescription();
    <T> Contents<T> putFullDescription(Contents<T> contents);
    String getSize();
}

Doesn't look all that complicated, does it? The problem is that the operations are not documented. Not here, and not in the actual source code. There are processing expectations however. So I will try to capture those by looking at the operations one by one:

void writeReference(ParaContents contents)

I think that this operation is expected to do is to generate a reference to the type of data structure it is supporting into the target document.

String getLabel()

I think what this operation is expected to do is to generate a refeference to the type of data structure it is supporting. However, since all this operation is capable of doing is return a String, that basically prevents it from generating a real link. (A link in the Pecia definition of the word. That is, something that eventually will be rendered into an HTML anchor tag, or a DocBook xref.)

ParaContents putOneLiner(ParaContents para)

I think what this operation is expected to do is to genenerate a single short description of itself into the output document. As far as I remember, this was done to allow you to generate a short description in a table for a field, and then make sure it includes a reference to something defined in detail elsewhere. Sort of similar to the way JavaDoc works.

boolean hasFullDescription()

Called to check if the next operation is implemented in a meaningful way.

Contents putFullDescription(Contents contents)

Similar to putOneLiner. However, in putOneLiner, it would be impossible to write outside a single paragraph. In putFullDescription, you can basically write a number of paragraphs, include tables, images, etc.

String getSize()

I think it is expected to return a human readable description of the size. Is it still required? That's hard to tell. Probably not, now we have getSizeExpr() on Codec.

So, as you can see, the contract is quite fragile. And there are a couple of other problems:

In some cases, you want the references to be inlined. In other cases, you want them to be part of the start of a sentence. Do you need to start whatever is generated with a capital? Or do you expect the framework to recognize when to change whatever you are generating into something starting with a capital?

As you can see, there is quite a bit of stuff that needs to be clarified or redefined. Question is, how? I will start to take a look at it tonight, and see if I can slowly refactor this to something that makes a little bit more sense, and is a little bit more helpful.