[lxml-dev] On lxml documentation

[Stefan Behnel]

Hi,

Marius Gedminas wrote:
> On Thu, Jan 08, 2009 at 10:55:30PM +0200, F Wolff wrote:
>> Just a quick word of thanks again for lxml and the wonderful
>> documentation. I'm currently optimising things a bit, and it is a joy.

I'm always happy to hear something other than complaints about the docs. ;)


>> What is the difference between a "child", a "descendant" and a
>> "subelement"?  I encountered these terms on this page:
>> http://codespeak.net/lxml/api/lxml.etree._Element-class.html
> 
> All children are descendants, but not all descendants are children.  A
> child of a child is also a descendant, as is a child of a child of a
> child, and so on for any intermediate number of child-ness.

Correct. The term "descendant" also represents an XPath axis, BTW, just
like child, preceding-/following-sibling, parent and ancestor.


> As far as I can tell, 'child' and 'subelement' are synonyms in this
> context.  (I imagine other XML libraries distinguish children that were
> elements from other kinds of children -- e.g. text nodes.)

I also tend to use the term "subelement" when I mean a real Element, as
opposed to comments, for example. But I'm pretty sure that's not very
consistent in the docs. While it reads nice in literature, variatio
sermonis is not the best element of style in technical documentation.


>> I want to suggest / request that new API functions have an indication
>> in the API docs of the version number when they were added. I believe
>> it is useful when needing to consider older versions of LXML.

I admit that that's helpful, it's just not done anywhere in the docs. Maybe
someone could come up with a script that extracts the existing API names
from a release. That would make it easy to run a diff and add the version
numbers to the API docstrings.

Stefan