- more up-to-date description of source tree

- better example of required comments for an API implementation
- replacement of WINE_PACKED by "pshpack1.h", etc.
- naming conventions for non-api calls and types
- location conventions for non-api header files and prototypes

DEVELOPERS-HINTS

@@ -1,6 +1,7 @@
 This document should help new developers get started. Like all of Wine, it
 is a work in progress.
 
+
 SOURCE TREE STRUCTURE
 =====================
 
@@ -23,19 +24,40 @@ KERNEL:
 GDI:
 
 	graphics/		- graphics drivers
-	graphics/x11drv/	- X11 display driver
+		x11drv/		- X11 display driver
-	graphics/metafiledrv/	- metafile driver
+		win16drv/	-> see below 
+		ttydrv/		- tty display driver
+		psdrv/		- PostScript graphics driver
+		metafiledrv/	- metafile drivr
+		enhmetafiledrv/	- enhanced metafile driver
 	objects/		- logical objects
 
 USER:
 
 	controls/		- built-in widgets
-	resources/		- built-in dialog resources
+	resources/		- built-in menu and message box resources
 	windows/		- window management
 
 Other DLLs:
 
-	dlls/*/			- Other system DLLs implemented by Wine
+	dlls/			- Other system DLLs implemented by Wine
+		advapi32/	- crypto, systeminfo, security, eventlogging
+		avifil32/	- COM object to play AVI files
+		comctl32/	- common controls
+		commdlg/	- common dialog boxes (both 16 & 32 bit)
+		imagehlp/	- PE (Portable Executable) Image Helper lib
+		msacm/		- audio compression manager (multimedia)
+		msacm32/	- audio compression manager (multimedia)
+		ntdll/		- NT implementation of kernel calls
+		psapi/		- process status API
+		rasapi32/	- remote access server API
+		shell32/	- COM object implementing shell views
+		tapi32/		- telephone API
+		ver/		- File Installation Library (16 bit)
+		version/	- File Installation Library (32 bit)
+		winaspi/	- 
+		winspool/	- Printing & Print Spooler 
+		wnaspi32/	- 
 
 Miscellaneous:
 
@@ -43,12 +65,16 @@ Miscellaneous:
 	multimedia/		- multimedia driver
 	ipc/			- SysV IPC based interprocess communication
 	win32/			- misc Win32 functions
+        ole/			- OLE code 
+		nls/		- National Language Support 
+				  configuration files
 
 Tools:
 ------
 
 	rc/			- old resource compiler
-	tools/			- relay code builder, new rc, etc.
+	tools/			- relay code builder, new rc, bugreport
+				  generator, wineconfigurator, etc.
 	documentation/		- some documentation
 
 
@@ -59,6 +85,8 @@ Binary loader specific directories:
 	if1632/			- relay code
 	miscemu/		- hardware instruction emulation
 	graphics/win16drv/	- Win16 printer driver
+        server/			- the main, controlling thread of wine
+        tsx11/			- thread-safe X11 wrappers (auto generated)
 
 Winelib specific directories:
 -----------------------------
@@ -67,6 +95,7 @@ Winelib specific directories:
 	libtest/		- Small samples and tests
 	programs/		- Extended samples / system utilities
 
+
 IMPLEMENTING NEW API CALLS
 ==========================
 
@@ -79,7 +108,8 @@ unimplemented call will look like (from gdi32.spec)
 To implement this call, you need to do the following four things.
 
 1. Find the appropriate parameters for the call, and add a prototype to
-[include/windows.h]. In this case, it might look like
+the correct header file. In this case, that means [include/wingdi.h],
+and it might look like
   BOOL WINAPI PolyBezierTo(HDC, LPCVOID, DWORD);
 If the function has both an ASCII and a Unicode version, you need to
 define both and add a #define WINELIB_NAME_AW declaration. See below
@@ -101,26 +131,38 @@ Add a function called 'PolyBezierTo' somewhere. Good things to put
 into a stub:
   o a correct prototype, including the WINAPI
   o header comments, including full documentation for the function and
-    arguments
+    arguments (see documentation/README.documentation)
   o A FIXME message and an appropriate return value are good things to
     put in a stub.
 
   /************************************************************
-   *  PolyBezierTo   (GDI32.269)  Draw many Bezier curves
+   *                    PolyBezierTo   (GDI32.269)  
+   *  
+   * Draw many Bezier curves
+   *
+   * RETURNS
+   *   nonzero on success or zero on faillure
    *
    * BUGS
    *   Unimplemented
    */
-   BOOL WINAPI PolyBezierTo(HDC hdc, LPCVOID p, DWORD count) {
+   BOOL WINAPI PolyBezierTo(HDC hdc,     /* handle to device context */
-	/* tell the user they've got a substandard implementation */
+                            LPCVOID p,   /* ptr to array of Point structs */
+                            DWORD count  /* nr of points in array */
+   ) 
+   {
+      /* tell the user they've got a substandard implementation */
       FIXME(gdi, ":(%x,%p,%d): stub\n", hdc, p, count);
-	/* some programs may be able to compensate, 
+
-           if they know what happened */
+      /* some programs may be able to compensate, 
+       * if they know what happened 
+       */
       SetLastError(ERROR_CALL_NOT_IMPLEMENTED);  
       return FALSE;    /* error value */
    }
 
-4. Implement and test the function.
+4. Implement and test the rest of the function.
+
 
 MEMORY AND SEGMENTS
 ===================
@@ -177,14 +219,24 @@ struct { BYTE x; WORD y; };
 
 will take 3 bytes under Windows, but 4 with gcc, because gcc will add a
 dummy byte between x and y. To have the correct layout for structures
-used by Windows code, you need to use the WINE_PACKED attribute; so you
+used by Windows code, you need to embed the struct within two special
-would declare the above structure like this:
+#include's which will take care of the packing for you:
+
+#include "pshpack1.h"
+struct {BYTE x; WORD y; };
+#include "poppack1.h"
+
+For alignment on a 2-byte boundary, there is a "pshpack2.h", etc.
+
+The use of the WINE_PACKED attribute is obsolete. Please remove these 
+in favour of the above solution. 
+Using WINE_PACKED, you would declare the above structure like this:
 
 struct { BYTE x; WORD y WINE_PACKED; };
 
-You have to do this every time a structure member is not aligned
+You had to do this every time a structure member is not aligned
 correctly under Windows (i.e. a WORD not on an even address, or a
-DWORD on a address that is not a multiple of 4).
+DWORD on a address that was not a multiple of 4).
 
 
 NAMING CONVENTIONS FOR API FUNCTIONS AND TYPES
@@ -234,6 +286,35 @@ and this will use the correct declaration depending on the definition
 of the UNICODE symbol.
 
 
+NAMING CONVENTIONS FOR NON-API FUNCTIONS AND TYPES
+==================================================
+
+Functions and data which are internal to your code (or at least shouldn't be
+visible to any WineLib or Windows program) should be preceded by
+an identifier to the module:
+
+Examples:
+
+ENUMPRINTERS_GetDWORDFromRegistryA()    (in dlls/winspool/info.c)
+IAVIFile_fnRelease()                    (in dlls/avifil32/avifile.c)
+X11DRV_CreateDC()                       (in graphics/x11drv/init.c)
+TIMER_Init()                            (implemented in windows/timer.c,
+                                         used in loader/main.c )
+
+if you need prototypes for these, there are a few possibilities:
+- within same source file only:
+  put the prototypes at the top of your file and mark them as prototypes.
+- within the same module:
+  create a header file within the subdirectory where that module resides,
+  e.g.  graphics/ddraw_private.h
+- from a totally different module, or for use in winelib:
+  put your header file entry in /include/wine/
+  but be careful not to clutter this directory!
+under no circumstances, you should add non-api calls to the standard
+windoze include files. Unfortunately, this is often the case, e.g.
+the above example of TIMER_Init is defined in include/message.h
+
+
 API ENTRY POINTS
 ================