We don’t generally use const for container types, because C’s concept of const is kind of shallow, and it’s a cast away from being ignored.
You’re not supposed to modify the returned list, but even if we marked it as const, you literally could access the data inside it and modify it in any case. On the other hand, we cannot change that compatibly this perfectly idiomatic code:
for (GList *iter = gtk_application_get_windows (app);
iter != NULL;
iter = iter->next)
{
// ...
}
would now emit a warning.
We sometimes change constness of in arguments, because it’s a source-compatible change; we don’t change the constness of return values, though.
The message is: Generics and defining elements of containers and arrays.
The gtk-doc message is less than helpful, sadly; but what it means is: the element-type annotation defines the actual type of the data inside the container type—which is a “generic” container, as it can hold anything pointer-sized. In other languages, these are called “generics”.
That you should only use the list for iteration at the point of use, and you should not keep it around “as is”. Additionally, you should not rely on the order of the list, as it might change even with focus changes. If you want to keep a list of top levels around, you should copy the GList yourself, and update it each time a top level is added or removed.