Posted by Robert.Panzer on Apr 15, 2015; 4:55pm
URL: https://discuss.asciidoctor.org/dev-Reorganization-of-the-AsciidoctorJ-AST-data-structures-tp2991.html

Hi,

as discussed with Dan and Alex we'd like to clean up the naming of the AST classes a little bit.
I'd like to make an initial proposal as a basis for an open discussion.

One point to pay attention to is the split into an API part and an Impl part of AsciidoctorJ.
This is necessary imo to support alternative implementations like a Nashorn or native Java implementation.

The following table shows the interfaces and classes of the org.asciidoctor.ast package.
The first column shows the current name.
If the class or interface should be renamed a proposed new name is in the second column.
The third column contains the destined part, either API or Impl.
At the same time everything in the API part is an interface, everything in the Impl part is a class.

AbstractNode      -> Node         API
AbstractNodeImpl  -> NodeImpl     Impl

AbstractNode was introduced recently and it's the base for all nodes, blocks as well as inlines etc.
Node probably better hits the point.
I think no one is already using these so it shouldn't be any problem to rename them.

AbstractBlock                     API 
AbstractBlockImpl                 Impl
Block                             API
BlockImpl                         Impl
Section                           API
SectionImpl                       Impl
DocumentRuby      -> Document     API
Document          -> DocumentImpl Impl

Looking back it's probably better to name the document interface `Document` instead of `DocumentRuby`, in particular with a Nashorn imply. ;-)
The document class will be renamed and the interface will jump into this open name.
Some interfaces will change to have Document instead of DocumentRuby in their interface, so this could require some changes in the users of the API.
Nevertheless there will be no changes for extensions because with the new extension proxies in AsciidoctorJ 1.6.0 the process methods carrying the `DocumentRuby` will completely disappear and the existing implementations will now get a `Document` interface instead of class. But that should be even binary compatible.


Inline                            API
InlineImpl                        Impl
ListNode          -> List         API
ListImpl                          Impl
ListItem                          API
ListItemImpl                      Impl


`ListNode` is also new, so no one has used that yet and the renaming should be without any consequences.


Then there are the classes below that are part of a parallel API, where I am quite unsure how much it is actually used.
At the moment these are all classes and I would suggest turning them all to interfaces and create new classes in the Impl part.

ContentPart
Author
DocumentHeader
RevisionInfo
StructuredDocument
Title

Would be awesome to get some feedback on this like how could it be done better, or what breaking changes do you see here that I didn't see.

Best regards,
Robert