On Fri, Jan 11, 2013 at 10:19:45AM +0100, Vinzenz Feenstra wrote:
Hi everyone,
We are currently documenting the API in vdsmapi-schema.json I noticed that we have there documented when a certain element newly is introduced using the 'Since' tag. However I also noticed that we are not documenting when a field was newly added, nor do we update the 'since' tag.
We should start documenting in what version we've introduced a field. A suggestion by saggi was to add to the comment for example: @since: 4.10.3
What is your point of view on this?
I do think it's a good idea to add this information. How about supporting multiple Since lines in the comment like the following made up example:
## # @FenceNodePowerStatus: # # Indicates the power state of a remote host. # # @on: The remote host is powered on # # @off: The remote host is powered off # # @unknown: The power status is not known # # @sentient: The host is alive and powered by its own metabolism # # Since: 4.10.0 - @FenceNodePowerStatus # Since: 10.2.0 - @sentient ##
Remember that any patch to change the schema format will require changes to process-schema.py as well.