getting rid of mkproto.sh from Samba3

[tridge at samba.org]

James,

 > If I have a decent header file, I can see the full interface in a  
 > single screen, along with comments, macros and typedefs. I don't think  
 > the argument about the extra typing involved in changing headers by  
 > hand is very strong, since the code needs to be read and understood  
 > thousands more times than it needs to be written.

It is not the extra typing, it's the mistakes. Before we had auto
prototypes in Samba the following mistakes were common:

 *) leaving a prototype in a header for a function that has been
  removed. I don't know of any tool that will find/remove those.

 *) getting details in the prototype wrong, especially the varargs
  functions with printf arguments. 

 *) when the arguments to a function change, and the prototype isn't
  updated. This is especially insidious when the new and old arguments
  are type compatible, but change their meaning, so the old prototype
  is completely misleading (ie. is still takes an int as the 3rd
  argument, but now its a set of flags, not a counter)

 *) once you start breaking up your includes out of a single
  includes.h, then you risk getting the prototype completely wrong if
  the source file of the function doesn't include the prototype
  header. The compiler won't complain.

 *) programmers add nice comments to the prototype header, which is in
  a completely different file to the code. Those comments will degrade
  over time as the code changes and the comment is not upgraded, so
  those nice docs that you do this month will become completely wrong
  by next year, and the person updating the function will not notice,
  as the prototype is not on the same screen as the code they are
  changing.

There is a very basic principle in programming that you should only
have a piece of information in one place in a program. If you have it
in two places then the two can become inconsistent. Auto generating
prototypes is an application of that principle.

If you want docs available when you haven't run make yet, then
generate them using funnelweb or similar tools. 

If you want to make finding functions easy, then break up the code
into modules, and use a module prefix for each module so all functions
in that module have an obvious xxxx_ at the start of the name. That is
the root cause of the name_to_fqdn(), global_myname(),
get_mydnsfullname() mess.

You should also be running findstatic.pl regularly to find unused
functions and functions that can be made static in a C file. That
means you won't have unused and redundent functions sitting around for
people to use. 

Cheers, Tridge