----- Original Message -----
From: "Adam Litke" agl@us.ibm.com To: "Vinzenz Feenstra" vfeenstr@redhat.com Cc: vdsm-devel@lists.fedorahosted.org Sent: Friday, January 11, 2013 9:03:19 AM Subject: Re: [vdsm] API Documentation & Since tag
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 ##
I don't like the fact that both lines don't point to the same type of token. I also don't like that it's a repeat of the type names and field names.
I prefer Vinzenz original suggestion (on IRC) of moving the "Since" token up and then have it be a state. It also makes discerning what entities you can use up to a certain version easier if you make sure to keep them sorted.
We can do this because the order of the fields and availability is undetermined (unlike real structs).
## # @FenceNodePowerStatus: # # Indicates the power state of a remote host. # # Since: 4.10.0 # # @on: The remote host is powered on # # @off: The remote host is powered off # # @unknown: The power status is not known # # Since: 10.2.0 # # @sentient: The host is alive and powered by its own metabolism # ##
The problem though is that it makes since a property of the fields and not of the struct. This isn't that much of a problem as we can assume the earliest version is the time when the struct was introduced.
Remember that any patch to change the schema format will require changes to process-schema.py as well.
-- Adam Litke agl@us.ibm.com IBM Linux Technology Center
vdsm-devel mailing list vdsm-devel@lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/vdsm-devel