Hi
Am 14.10.19 um 22:48 schrieb Tim.Bird@sony.com:
-----Original Message----- From: Jani Nikula on October 13, 2019 11:00 PM On Sun, 13 Oct 2019, Changbin Du changbin.du@gmail.com wrote:
The 'functions' directive is not only for functions, but also works for structs/unions. So the name is misleading. This patch renames it to 'specific', so now we have export/internal/specific directives to limit the functions/types to be included in documentation. Meanwhile we
improved
the warning message.
Agreed on "functions" being less than perfect. It directly exposes the idiosyncrasies of scripts/kernel-doc. I'm not sure "specific" is any better, though.
I strongly agree with this. 'specific' IMHO, has no semantic value and I'd rather just leave the only-sometimes-wrong 'functions' than convert to something that obscures the meaning always.
Perhaps "symbols" would be more self-explanatory. Or, actually make "functions" only work on functions, and add a separate keyword for other stuff. *shrug*
My preference would be to use 'symbols'. I tried to come up with something but 'symbols' is better than anything I came up with.
Maybe 'interfaces' or 'artifacts'. The term 'symbols' is just as imprecise as 'functions'.
Best regards Thomas
Seems like the patch is way too big. I'd probably add "symbols" (or whatever) as a synonym for "functions" for starters, and convert documents piecemeal, and finally drop the old one.
The scripts/kernel-doc change should be a patch of its own.
Agreed on these two points as well.
Just adding my 2 cents. -- Tim _______________________________________________ dri-devel mailing list dri-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/dri-devel