----- Original Message -----
From: "Adam Litke" <agl(a)us.ibm.com>
To: "Vinzenz Feenstra" <vfeenstr(a)redhat.com>
Cc: vdsm-devel(a)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(a)us.ibm.com>
IBM Linux Technology Center
_______________________________________________
vdsm-devel mailing list
vdsm-devel(a)lists.fedorahosted.org
https://lists.fedorahosted.org/mailman/listinfo/vdsm-devel