Caveat: I am no JNDI expert. The little I do know is gleaned from reverse engineering Tomcat's JNDI implementation.
I think the example is wrong because it binds a reference. A reference will always result in a new object being created when it is looked up. If the example binds a BasicDataSource instance, it appears to behave as desired/expected.
As most users expect multiple JNDI look ups using the same name to return the same object, Tomcat deliberately breaks the rules. By default, when Tomcat finds a reference, Tomcat resolves that reference to an object and then replaces the reference in JNDI with the object. In later Tomcat versions, this is configurable with the singleton property.
It isn't clear to me how implementing Referenceable will help. If anything, that will make it worse as it would then be impossible to bind an instance of a BasicDataSource to JNDI as the Reference would be bound.
I intend to tweak the examples to bind instances rather than References. This appears to be consistent with Ondrej Tisler's approach above.