[jdom-interest] META: Children of a lesser spec

[Brett McLaughlin]

"Peter V. Gadjokov" wrote:
> 
> >Now, if it was only correct. But it isn't, and a cursory reading of _any_
> >XML specification makes it confusing, especially getChildren()...
>   - Brett McLaughlin, during a JDOM API design discussion, emphasis mine
> 
> When we speak of spec conformance in the context of API design discussions,
> what spec are we talking about? What spec, if any, _should_ we be talking
> about? If we could settle this philosophical issue, some of the ongoing API
> discussions could become somewhat clearer.
> 
> So, to get this going, the classes of specification and my view of their
> applicability:
> 
> *] Core 'syntax-oriented' specs, e.g., The XML spec, the Namespace spec.
> 
> These specifications both define core features and their syntactical
> representation in a well-formed, serialized XML document. Since a useful API
> would do well to stay as syntax-independent as possible, I'd argue these
> should not drive API-level decisions. Obviously, since they contain

What? JDOM is an XML /model/ so how can we possibly ignore what XML says
about that model? If what JDOM represents is data that is defined by
this specification, how can we possibly not use this specification to
model that data? Otherwise, we wouldn't use the term Processing
Instruction, or XML Declaration, or Doctype. I don't buy this.

> information that goes beyond syntax, they should be consulted and taken into
> serious consideration - the hard requirements of conformance, though, are
> constrained to Builders and Outputers, not the core API.
> 
> *] Other API specs, most notably DOM
> 
> Since one of the driving motivations behind JDOM is to be better (and not as
> cumbersomeas ) than DOM, DOM should not be a significant driver of API
> decisions. It should certainly serve as a source of ideas (both good and
> bad) but familiarity with DOM and DOM-inspired expectations should be
> secondary constraints during API design - the primary ones being usefulness,
> clarity and elegance.

Agreed, 100%, on this one.

> 
> *] Core 'syntax-independent' specs, e.g., the XML Infoset (any others?)
> 
> These, I think, are a lot more relevant to in API discussions than the
> previous ones. They describe XML documents and their components in terms of
> logical structure as opposed to syntax (or serialization format). Such specs
> should carry more weight in discussion than any other factor with the
> exception of the ones directly related to creating a sensible, OO, Java API
> - i.e. only the needs of API usefulness, clarity and elegance should
> override the requirements of conceptual specs (e.g. JDOM could chose to hide
> some of the conceptual complexity as mentioned in the JDOM philosophy FAQ).
> In the appropriate places, the API design and usage documentation should
> refer to concepts of such specs, describing how JDOM maps to and differs
> from the concepts outlined in those specs. In a word, this is the task of
> making the M in JDOM meaningful.


M in JDOM doesn't mean anything ;-) Even on these grounds, you will find
that XML Infoset clearly defines content, and children.