| Message ID | 20161016210347.GA4484@veronia-Lenovo-IdeaPad-S400 (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On 16/10/2016 23:03, Veronia Bahaa wrote: > Add documentation to the functions id_generate and id_wellformed in include/qemu/id.h > > Signed-off-by: Veronia Bahaa <veroniabahaa@gmail.com> > --- > include/qemu/id.h | 23 +++++++++++++++++++++++ > 1 file changed, 23 insertions(+) > > diff --git a/include/qemu/id.h b/include/qemu/id.h > index 40c7010..7bbcdc0 100644 > --- a/include/qemu/id.h > +++ b/include/qemu/id.h > @@ -7,7 +7,30 @@ typedef enum IdSubSystems { > ID_MAX /* last element, used as array size */ > } IdSubSystems; > > +/** > + * id_generate: Generates an ID of the form PREFIX SUBSYSTEM NUMBER > + * where: > + * > + * - PREFIX is the reserved character '#' > + * - SUBSYSTEM identifies the subsystem creating the ID > + * - NUMBER is a decimal number unique within SUBSYSTEM. > + * > + * Example: "#block146" > + * > + * Returns the generated id string for the subsystem > + * > + * @id: the subsystem to generate an id for > + */ > char *id_generate(IdSubSystems id); > + > +/** > + * id_wellformed: checks that an id starts with a letter > + * followed by numbers, digits, '-','.', or '_' > + * > + * Returns %true if the id is well-formed > + * > + * @id: the id to be checked > + */ > bool id_wellformed(const char *id); > > #endif > Queued, thanks. Paolo
Veronia Bahaa <veroniabahaa@gmail.com> writes: > Add documentation to the functions id_generate and id_wellformed in include/qemu/id.h > > Signed-off-by: Veronia Bahaa <veroniabahaa@gmail.com> > --- > include/qemu/id.h | 23 +++++++++++++++++++++++ > 1 file changed, 23 insertions(+) > > diff --git a/include/qemu/id.h b/include/qemu/id.h > index 40c7010..7bbcdc0 100644 > --- a/include/qemu/id.h > +++ b/include/qemu/id.h > @@ -7,7 +7,30 @@ typedef enum IdSubSystems { > ID_MAX /* last element, used as array size */ > } IdSubSystems; > > +/** > + * id_generate: Generates an ID of the form PREFIX SUBSYSTEM NUMBER > + * where: > + * > + * - PREFIX is the reserved character '#' > + * - SUBSYSTEM identifies the subsystem creating the ID > + * - NUMBER is a decimal number unique within SUBSYSTEM. > + * > + * Example: "#block146" > + * > + * Returns the generated id string for the subsystem > + * > + * @id: the subsystem to generate an id for > + */ This copies the function comment from the definition. Not a good idea, because the copies are prone to get inconsistent over time. There are two schools of thought on where to put function comments: next to the definition, or next to a declaration. The latter school argues that it produces headers that do double-duty as interface documentation. The former school points out that separating the function comment from the actual function reduces the chance of the function comment to stay correct. Also, editors worth using can take you to the definition quickly. id.c and id.h conform to the the latter school. Changeable, but change requires justification. > char *id_generate(IdSubSystems id); > + > +/** > + * id_wellformed: checks that an id starts with a letter > + * followed by numbers, digits, '-','.', or '_' > + * > + * Returns %true if the id is well-formed > + * > + * @id: the id to be checked > + */ > bool id_wellformed(const char *id); > > #endif Here's my try: /* * Is @id a well-formed identifier? * * Well-formed identifiers consists only of letters, digits, '-', '.' * and '_', starting with a letter. */
diff --git a/include/qemu/id.h b/include/qemu/id.h index 40c7010..7bbcdc0 100644 --- a/include/qemu/id.h +++ b/include/qemu/id.h @@ -7,7 +7,30 @@ typedef enum IdSubSystems { ID_MAX /* last element, used as array size */ } IdSubSystems; +/** + * id_generate: Generates an ID of the form PREFIX SUBSYSTEM NUMBER + * where: + * + * - PREFIX is the reserved character '#' + * - SUBSYSTEM identifies the subsystem creating the ID + * - NUMBER is a decimal number unique within SUBSYSTEM. + * + * Example: "#block146" + * + * Returns the generated id string for the subsystem + * + * @id: the subsystem to generate an id for + */ char *id_generate(IdSubSystems id); + +/** + * id_wellformed: checks that an id starts with a letter + * followed by numbers, digits, '-','.', or '_' + * + * Returns %true if the id is well-formed + * + * @id: the id to be checked + */ bool id_wellformed(const char *id); #endif
Add documentation to the functions id_generate and id_wellformed in include/qemu/id.h Signed-off-by: Veronia Bahaa <veroniabahaa@gmail.com> --- include/qemu/id.h | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)