This new scheme makes certain things more consistent but there is still room for improvement by using a common style of debug messages. Before I continue, let me note that the output format is the following:
yyy:xxx:fff <message> where: yyy = the class (fixme, err, warn, trace) xxx = the channel (atom, win, font, etc) fff = the function name |
these fields are output automatically. All you have to provide is the <message> part.
So here are some ideas:
do NOT include the name of the function: it is included automatically
if you want to output the parameters of the function, do it as the first thing and include them in parentheses, like this:
YYY(xxx, "(%d,%p,etc)...\n", par1, par2, ...); |
for stubs, you should output a FIXME message. I suggest this style:
FIXME(xxx, "(%x,%d...): stub\n", par1, par2, ...); |
output 1 and ONLY 1 line per message. That is, the format string should contain only 1 \n and it should always appear at the end of the string. (there are many reasons for this requirement, one of them is that each debug macro adds things to the beginning of the line)
if you want to name a value, use = and NOT :. That is, instead of saying:
FIXME(xxx, "(fd: %d, file: %s): stub\n", fd, name); |
FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name); |
try to avoid the style:
FIXME(xxx, "(fd=%d, file=%s)\n", fd, name); |
FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name); |
if you output a string s that might contain control
characters, or if s may be
NULL, use
debugstr_a
(for ASCII strings, or
debugstr_w
for Unicode strings) to
convert s to a C string, like this:
HANDLE32 WINAPI YourFunc(LPCSTR s) { FIXME(xxx, "(%s): stub\n", debugstr_a(s)); } |
if you want to output a resource identifier, use debugres to convert it to a string first, like this:
HANDLE32 WINAPI YourFunc(LPCSTR res) { FIXME(xxx, "(res=%s): stub\n", debugres(s)); } |
PTR_SEG_TO_LIN
to get a
liner pointer first:
HRSRC16 WINAPI FindResource16( HMODULE16 hModule, SEGPTR name, SEGPTR type ) { [...] TRACE(resource, "module=%04x name=%s type=%s\n", hModule, debugres(PTR_SEG_TO_LIN(name)), debugres(PTR_SEG_TO_LIN(type)) ); [...] } |
for messages intended for the user (specifically those that
report errors in wine.conf), use the
MSG macro. Use it like a
printf
:
MSG( "Definition of drive %d is incorrect!\n", drive ); |
For structure dumps, use the DUMP
macro. Use it like a printf
, just like
the MSG macro. Similarly, there are only
a few valid uses of this macro. Grep the source to see when
to use it.