Distributed Reflections of the Third Kind

The last couple of weeks, I spend most of my commuting time on redesiging the CodecDescriptor in Preon. And I think I'm getting there. Find the results below. I am currently trying to work this into the different existing Codecs. Not even halfway yet, but I think I will be able to get there this week.

Now, one of the important changes that this new CodecDescriptor introduces is the Documenter. I want to rename that into something a little bit more sensible. Anybody with a good idea on that, please send your suggestions. ;-)

The Documenter has been in Pecia for a while, but you could only use it in a paragraph context. I am making changes to Pecia now to use it all over the place. It would be good to have another name for it though. (Did I already mention that?)

Anyway, the Documenter - or whatever its name is going to be - is an object that is capable of rendering itself into a certain context. It works like a callback. If you pass the Documenter to - say - a paragraph, then the paragraph will turn around and ask the Documenter to render itself.

package nl.flotsam.preon;

import nl.flotsam.pecia.Contents;
import nl.flotsam.pecia.Documenter;
import nl.flotsam.pecia.ParaContents;

public interface CodecDescriptor {

   /**
    * An enumeration with different adjectives.
    */
   public enum Adjective {
       A, THE, NONE;
      
       public String asTextPreferA() {
           switch(this) {
               case A: return "a ";
               case THE: return "the ";
               default: return "";
           }
       }

       public String asTextPreferAn() {
           switch(this) {
               case A: return "an ";
               case THE: return "the ";
               default: return "";
           }
       }
      
   }

   /**
    * Returns an object capable of writing a one-line summary of the data
    * structure. Expect the summary to be printed at the beginning of a
    * paragraph, but make sure the paragraph is ended in such a way that more
    * lines might be appended to that paragraph, if required, by some other
    * component. I.e. make sure you end with a dot-space. (". ") Typically
    * starts with {@link Adjective#A}. 
    *
    */
   <C extends ParaContents<?>> Documenter<C> summary();

   /**
    * Returns an object capable of rendering a short reference to the type of
    * data for which the Codec provides the decoder. This reference should
    * <em>at least</em> include a reference to the type of data decoded by
    * 'sub'-Codecs. The {@link Adjective} argument allows the implementor to
    * generate a correct reference, such as 'a list' instead of 'an list'.
    *
    * <p>
    * Note that implementers should assume that the particular piece of data
    * that is going to be referenced here will be detailed further along the
    * road. Unless {@link #requiresDedicatedSection()} returns
    * <code>true</code>, that could be within the same section.
    * </p>
    *
    * @param adjective
    *            The adjective to use; <code>null</code> if no adjective should
    *            be used.
    */
   <C extends ParaContents<?>> Documenter<C> reference(Adjective adjective);

   /**
    * Returns an object capable of writing detailed information on the format
    * to the document section passed in. Typically implemented by writing a
    * (couple of) paragraph(s), and forwarding to the CodecDescriptor of a
    * nested {@linkplain Codec}. Note that - while forwarding - the descriptor
    * has the option to replace the way the buffer is referenced.
    *
    * @param bufferReference
    *            A String based human readable reference to the encoded data.
    */
   <C extends Contents<?>> Documenter<C> details(String bufferReference);

   /**
    * Returns a boolean indicating if the type of data for which the Codec
    * provides the decoder should be documented in a dedicated section.
    *
    * @return A boolean indicating if the type of data for which the Codec
    *         provides the decoder should be documented in a dedicated section:
    *         <code>true</code> if it does; <code>false</code> if it doesn't.
    */
   boolean requiresDedicatedSection();

   /**
    * Returns the title of the section to be rendered, in case
    * {@link #requiresDedicatedSection()} returns <code>true</code>.
    *
    * @return The title of the section to be rendered, in case
    *         {@link #requiresDedicatedSection()} returns <code>true</code>.
    */
   String getTitle();

}

Preon changes