Damon:
I don't really think we can ask people to add a stability level to all pieces of documentation. That is just too much hassle. So for most GNOME libraries we need to default to "Stable".
I should point out that I'm happy to update the gtk-docs for libraries that would be the biggest hassle. In other words, the libraries that are known to be 100% stable (pango, glib, gtk). So if the only hang up is that it will be a bit of a hassle for these libraries, then that shouldn't be such a problem. Also, I'd argue that most GNOME libraries are not, in fact, Stable. We had a discussion on desktop-devel-list and developers seemed only able to agree that a handful of libraries in the GNOME stack were really Stable.
Also, I don't see the point in adding "Stability Level: Stable" to everything in the output documentation, so if it is stable it should be skipped.
This also doesn't really help the case where the entire library is considered to be unstable. Something else may be needed there.
I do agree with you that it is important to make the feature easy to use, and I also agree with you that it would be useful to make shortcuts to avoid having to enter the same "Stability Level: Stable" entry for every function in a grouping of functions that has the same stability level.
However, I worry that simply making the default "Stable" and not printing out any output for the default will discourage its use and undermine its usefulness. Can't we think of an approach that makes the documentation a bit easier without undermining the feature?
Remember that by defining an interface to be Stable, the interface developer is *guaranteeing* that the interface will not change until the next major release. Accidently mislabelling an Unstable or Private interface as Stable could therefore cause a big problem. Accidently mislabelling a Stable interface as Private or Unstable is a much less severe problem. In other words, its dangerous to default a stability level to the most restrictive stability level. You risk the situation where a developer uses interface x and thinks it is safe because it is marked as "Stable", then finds out later that it is really Unstable or Private and got accidently marked as Stable due to defaults.
Furthermore, as you point out some libraries will be mostly Stable and other libraries will be mostly Unstable. Making the default one or the other makes it easy for some libraries and hard for others.
Perhaps one approach would be to make the default "Undefined" as was suggested by Peter Williams and not print out anything about Stability Levels in that case. This way, stability information will only be printed for libraries that actually take the time to document them.
Perhaps a way we could make it easier to document would be to allow a comment in a file that says "all interfaces in this file have stability level xyz". I'm not sure if this is possible with the way gtk-doc works, but it might be a way to make things work.
I don't really see a problem with adding the "Stability Level: xyz" to every interface in the generated output, but we could perhaps do something like put a message at the top or bottom of the page saying "Stability Level: xyz" just once if all the interfaces on that page are the same level.
Anyway, I've offered some more suggestions about how we could implement this feature in ways that might be less painful. Perhaps we can come up with a creative solution that allows stability levels to be documented in a way that won't accidently cause unstable/private functions to get labeled as Stable. Perhaps we can also send an email to desktop-devel-list and see what people think there. I started a thread there about Interface Stability and people generally seemed interested in having this feature. That way we can get some feedback from the people the change would impact rather than assuming what would be considered a hassle and what people consider reasonable.
Brian
_______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
