DEBUG Docs.

[Christopher R. Hertel]

> The only bit I don't like is DEBUGHDR() with the file and function
> name. 

I knew you wouldn't...  ;)

> I think we should never be typing the file and function name
> ourselves. 

We already do this all over the place.  We need the function name as a
reference.  Without them it's hard to know where the error took place. 

> I know that means we only get file:line on some (many?) platforms, but
> I think that is quite good enough. (in fact, file:line gives you more
> precise info than the function name gives!)

Not really.  The __LINE__ will tell you the line number of the DEBUG() 
call only.  That will let you search through until you find the function, 
but you'd still need to look at the code to figure out why the DEBUG() 
message spit out whatever it spit out.

Another problem with file:line is that __LINE__ is an int while
__FUNCTION__ is a string.  That means that you really have to decide (at
config or compile time) which format you are going to use.  Can't have it
both ways. 

> I suppose this is a similar issue to the auto-proto stuff. I am a
> strong believer in never typing something which is already
> available. It just leads to mistakes.

Agreed, in principle.

> We have file:line available on all platforms. We have file:function
> available on many. Let's use them!

We *probably* have file:line availalble on all platforms.  I already know 
that SGI doesn't have __FUNCTION__ (pain).

My opinion is that the function name is much more useful than the line
number.  The function names in nmbd are very descriptive (haven't done
enough digging into smbd yet), so it's quite helpful to have them.

Still, I don't disagree overall.  Perhaps there's a compromise here:

- If __FUNCTION__ is available, then we would use file:function().
- If it's not, then we would use file:line.
- In either case, the first line of the body of the message could be the
  function name, typed in by the programmer. 

This last is, as I've mentioned, already done in many places because 
people really do use the function name.

I'd like to hear some other opinions on this.  Luke?  Jeremy?  Anyone?

Chris -)-----

-- 
Christopher R. Hertel -)-----                   University of Minnesota
crh at nts.umn.edu              Networking and Telecommunications Services