Hi all. I'm trying to search for information on something I recall was discussed here in the past, but I'm having no luck turning up anything close to being relevant.

I'm working on a mini DSL for the construction of executable Statecharts/HSM's, but I've become aware that the method currently in use is a tangle of what I think should be separate concerns.

Right now, the actual executable machine is built piece by piece after each new declaration. There are issues with this approach such as: [1] The definition of the machine doesn't exist anywhere (There are instances where I have to extract information from what is essentially the final form of the machine and combine that with ad hoc trees/lists generated from the declarations, to be able to construct it incrementally (car, cdr, assoc hell)), [2] The final form of the executable machine is tied to a specific implementation strategy right from the start. [3] The language used to construct the machines is fixed and cannot be changed without rewriting the entire library. Essentially the DSL input/output is set in stone and gives no easy opportunity for experimentation and exploration within the different stages of definition and construction of the Statecharts.

I have seen some discussion in the past on the issue of documentation, specifically creating a set of classes to capture descriptions of well-defined entities that one may expect to exist in a piece of documentation. With the intention to separate the concerns of input and output formats/syntax from the content/essence of the documentation itself.

I have a vague idea of how I might accomplish this in my use-case, but I would like to read about how others have accomplished this, so I can make use of their experience. Unfortunately I have no idea of the search terms to use to summon the information from google. I have tried search terms like "class", "object", "descriptor", "description", "serialization".