On 2020-08-23 08:21, Nicolas George wrote:
Since the idea of documentation built in the libraries seems popular, I
have tried to outline an API to access it.…
See the attached file […`documentation.c` omitted…].
Some comments about the API outline itself, from `documentation.c`:
struct AVDocNode {
/**
* Names of the component.
*
* It is a concatenation of 0-terminated strings, terminated by
an empty
* string (i.e. a double 0).
* For example "frame_rate, rate, r" would be
"frame_rate\0rate\0r\0\0".
* The first name is the main name of the component, the other are
* aliases.
* If this field is used as a plain C string, it contains only
the main
* name.
*/
const char *names;
The type "const char *" implies a single null-terminated string. Is it
usual in the codebase to use it to refer to a concatenation of
null-terminated strings? It seems that having a type which means
"concatenation of null-terminated strings" would be clearer.
How is this concatenation itself terminated? If I am walking the
null-terminated strings with a char * pointer, how do I know I have
reached the end? I don't see this defined. You could say that a
null-terminated string of length zero terminates it. This then requires
that the other strings in `names` have length >= 1.
/**
* Unique identifier of the compnent.
*
* It is composed of alphanumeric characters plus underscore
and slash
* and written hierarchically.
*
* For example, the width option of the scale filter would be
* "lavfi/vf_scale/opt_width".
*
* This identifier can be used for links in the text.
*
* It matches the symbol that makes the documentation
available, in the
* avdoc_ namespace with double underscore standing for slashes:
* extern const AVDocNode avdoc_lavfi__vf_scale__opt_width;
*/
const char *id;
This attribute is defined as a "unique identifier", but the example
value alludes to sort of path through a hierarchy. If values have a
path-like structure, sooner or later clients will start to parse that
structure, then depend on it. If you don't want them to do that, then
perhaps state that this value is opaque, and give an example which is a
universally unique but arbitrary value. If you do want them to do that,
then be explicit about what the internal structure is.
/**
* Links towards other nodes.
*
* All nodes linked in the text must have an entry here, but
implicit
* links are possible too, for example the type of an option.
*
* The types are ordered by type.
*/
const AVDocLink *links;
The type AVDocLink * implies a pointer to a single AVDocLink, but the
plural word "links" implies that this is an array of AVDocLink
structures. If you intend this pointer to point to an array, I suggest
you make that clear. Also, how will a client know how long the array is?
Will there be a sentinal AVDocLink value which means "end of array"?
const char *id;
const char *title;
const char *text;
The termination of these strings is not specified. I suspect you mean
them to be null-terminated C strings, but it is perhaps better to say so
explicitly.
Also, a narrative of how this API is used would be helpful. Who calls
it? What is the structure of AVDocNodes expected to be returned? What is
the client expected to do with this?
Also, out of scope of an API doc, but since I'm here: I'd be interested
to see how this structure is serialised in the executable file. How are
the AVDocNodes delimited from one another? How are AVDocLink values
serialised? Will there be a version field in the serialised structure?
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
