Using XML with Legacy Business Applications

Comments and Documentation

Apparently, many people have bought into the notion that XML is self-documenting. Or maybe they subscribe to the old programming adage, “It was hard to write. It should be hard to read!” Whatever the case, not everyone believes in documenting his or her schemas. For the blessed folks who do, schema language offers two choices. You will see both in the schemas you use.

• xs:documentation Element inside an xs:annotation Element: This is the preferred style. When used in this fashion, tools such as schema authors display the documentation nicely. You can see a few such examples throughout this chapter.

• XML comments: The traditional style of creating XML comments by using the start (<!--) and end (-->) characters is allowed ...