
                              Wine Documentation                               
Prev                       Chapter 8. Debug Logging                        Next
-------------------------------------------------------------------------------

A Few Notes on Style

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, ...);              
                                                                       
    That is, you output the parameters, then a : and then a string containing
    the word "stub". I've seen "empty stub", and others, but I think that just
    "stub" suffices.
   
*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);                
                                                                       
    say:
    FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);                  
                                                                       
    use : to separate categories.
   
*try to avoid the style:
    FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);                  
                                                                       
    but use:
    FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);                  
                                                                       
    The reason is that if you want to grep for things, you would search for
    FIXME but in the first case there is no additional information available,
    where in the second one, there is (e.g. the word stub)
   
*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));                   
    }                                                                  
                                                                       
    if the resource identifier is a SEGPTR, use 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 );            
                                                                       
    However, note that there are very few valid uses of this macro. Most
    messages are debugging messages, so chances are you will not need to use
    this macro. Grep the source to get an idea where it is appropriate to use
    it.
   
*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.
   

-------------------------------------------------------------------------------
Prev                                  Home                                 Next
Compiling Out Debugging                Up                       COM/OLE in Wine
Messages                                                                       
