[FFmpeg-devel] [RFC] Built-in documentation API

[Jim DeLaHunt]

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?