From: Dimitri Papadopoulos-O. <dim...@ce...> - 2006-05-09 08:15:38
|
Hi again, > As the new kid on the admin block, I'm a bit reticent about throwing my= =20 > hat into this ring; however, IMO this style of ChangeLog entry, with=20 > asterisks replacing swathes of arbitrary and unspecified symbol names,=20 > should not be tolerated. It is explicitly discouraged by the GNU Codin= g=20 > Standards, on which our ChangeLog style is modelled; indeed, it could b= e=20 > argued that it is implicitly forbidden. OK, I've read again the relevant part of the GNU coding standards and=20 indeed: It's important to name the changed function or variable in full. Don't abbreviate function or variable names, and don't combine them. Subsequent maintainers will often search for a function name to find all the change log entries that pertain to it; if you abbreviate the name, they won't find it when they search. Note however that I've just replicated the existing w32api ChangeLog=20 style. Therefore I don't know how much the GNU coding standards apply to=20 w32api. Actually I believe the GNU coding standards do not fit w32api headers=20 well for two reasons: 1) The changes to w32api are very specific. For example what if I add=20 hundreds of line looking like: #define FOOBAR01 0x0001 #define FOOBAR02 0x0002 #define FOOBAR03 0x0003 ... That's very typical of w32api changes and I don't see why I should=20 duplicate the information in ChangeLog - it's already in the diff.=20 Actually I think this would make the ChangeLog unreadable: * include/header.h (FOOBAR01,FOOBAR02,FOOBAR03,FOOBAR04) (FOOBAR05,FOOBAR06,FOOBAR07,FOOBAR08,FOOBAR09,FOOBAR10) ... (FOOBAR96,FOOBAR97,FOOBAR98,FOOBAR99): Define. 2) Until now it was unfortunately impossible to put comments into the=20 code, for the sake of faster parsing of header files. The GNU coding=20 standards specify: There's no need to describe the full purpose of the changes or how they work together. If you think that a change calls for explanation, you're probably right. Please do explain it=97but please put the explanation in comments in the code, where people will see it whenever they see the code. For example, =93New function=94 is enough for the change log when you add a function, because there should be a comment before the function definition to explain what it does. So the explanations have to be put in the ChangeLog. Unless... Since GCC=20 4 supports precompiled headers, would it be possible to add some minimal=20 comments in the header files? I was thinking of a mere link to the=20 relevant documentation, something like: //http://msdn.microsoft.com/library/.../directshowstructures.asp typedef struct _DSFooBar { ... } DSFooBar; typedef struct _DSStruct { ... } DSStruct; In the case where the documentation is wrong or missing, a more detailed=20 explanation could be added. In short, this is a proposal to group macros, functions, structures=20 together according to the MSDN page they belong to, after a one-line=20 comment that is a link to that page. I think this would: 1) help maintain w32api, 2) make clear to everyone contributions should rely on the MSDN. Dimitri Papadopoulos |