POM reference for <properties> is incomplete and misleading

See http://jira.codehaus.org/browse/MJAVADOC-303?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=264846#action_264846

The POM reference at http://maven.apache.org/pom.html#Properties is misleading - it does not document the syntax for <properties> but says "Maven properties are value placeholder, like properties in Ant." so I mistakenly assumed Ant syntax, and some examples on that page are in an <activation> element which use

<property>
<name>mavenVersion</name>
<value>2.0.3</value>
</property>

syntax, but this is misleading

Apparently, <properties> uses the syntax

<properties>
<some-property-name>some-property-value</some-property-name>
<another-property-name>another-property-value</another-property-name>
</properties>

but the reference doc does not state this clearly, only showing

<properties>...</properties>