[jdom-interest] getMixedContent -> getContent

[guru at stinky.com]

On Wed, Jun 27, 2001 at 11:12:51AM -0400, Alex Rosen wrote:
> it's not obvious from the name what the difference is between
> getContent() and getChildren(). I think too easy to confuse.

Yes, it's always been so.  IMHO, we should do an s/Children/Elements/
on the API.  

That is, it's a matter of personal intuition whether the term "child"
refers to "a child node that is an element" or "any child node of any
type".  Personally, I feel it means the latter, but the very existence
of the ambiguity means either

(a) you define "content" as "all children" and "elements" as "all
child nodes that are elements", leading to

	getChild("foo") -> getElement("foo")
	getChildren() -> getElements()
	getChildren("foo") -> getElements("foo")
	getChildText("foo") -> getElementText("foo")
	getChildTextTrim("foo") -> getElementTextTrim("foo")

or

(b) you accept the consequences and have to explain very clearly what
"children" means every time someone asks, and why a String or a
Comment in the content of an element is not actually a child of that
element.

I think that renaming child->element would not cause any confusion,
especially since the method signatures involved force programmers to
specify *which* child elements they're talking about.  Programmers
understand recursion; it's not a mind-blowing experience to say
element.getElement("foo").

Then the difference referred to above will be between getContent() and
getElements() -- no confusion.

However, I've grown fond of getChild, so I won't go to the mat for
this.  Just couldn't resist making my point again. :-)

(On the subject of MixedContent vs Content, I think the current
definition of "content" is perfectly reasonable and intuitively
clear, so the renaming should stand, since it's more concise.)

> Or, I wonder if getContents() or getAllContents() would be more
> appropriate than getContent()?

No, "content" is a plural noun (technically a mass noun or a non-count
noun) already; no need to add an ess.

 - A

-- 
Alex Chaffee                       mailto:alex at jguru.com
jGuru - Java News and FAQs         http://www.jguru.com/alex/
Creator of Gamelan                 http://www.gamelan.com/
Founder of Purple Technology       http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/