mextra docs

diff --git a/include/mextra.h b/include/mextra.h
index 93478efd17adfd377e424deca335cc7844098764..f358e02827d87089553dfa049f8aaa3985682a6c 100644 (file)
--- a/include/mextra.h
+++ b/include/mextra.h
@@ -1,4 +1,4 @@
-/*     SCCS Id: @(#)mextra.h   3.5     2006/01/03      */
+/*     SCCS Id: @(#)mextra.h   3.5     2006/01/07      */
 /* Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1985. */
 /* NetHack may be freely redistributed.  See license for details. */
 
@@ -9,6 +9,54 @@
 #include "align.h"
 #endif
 
+/*
+ *  Adding new mextra structures:
+ *
+ *      1. Add the structure definition and any required macros in this file
+ *         above the mextra struct.
+ *      2. Add a pointer to your new struct to the mextra struct in this file.
+ *      3. Add a referencing macro at the bottom of this file after the mextra
+ *          struct (see MNAME, EGD, EPRI, ESHK, EMIN, or EDOG for examples).
+ *      4. Create a newXX(mtmp) function and possibly a free_XX(mtmp) function
+ *          in an appropriate new or existing source file and add a prototype
+ *         for it to include/extern.h.
+ *
+ *             void FDECL(newXX, (struct monst *));
+ *             void FDECL(free_XX, (struct monst *));
+ *     
+ *               void
+ *               newXX(mtmp)
+ *               struct monst *mtmp;
+ *               {
+ *                   if (!mtmp->mextra) mtmp->mextra = newmextra();
+ *                   if (!XX(mtmp)) {
+ *                       XX(mtmp) = (struct XX *)alloc(sizeof(struct XX));
+ *                       (void) memset((genericptr_t) XX(mtmp),
+ *                                  0, sizeof(struct XX));
+ *                   }
+ *               }
+ *     
+ *      5. Consider adding a new makemon flag MM_XX flag to include/hack.h and
+ *         a corresponding change to makemon() if you require your structure
+ *          to be added at monster creation time. Initialize your struct
+ *         after a successful return from makemon().
+ *
+ *          src/makemon.c:  if (mmflags & MM_XX) newXX(mtmp);
+ *          your new code:  mon = makemon(&mons[mnum], x, y, MM_XX);
+ *
+ *      6. Adjust size_monst() in src/cmd.c appropriately.
+ *       7. Adjust dealloc_mextra() in src/mon.c to clean up
+ *         properly during monst deallocation.
+ *      8. Adjust restmonchn() in src/restore.c to deal with your
+ *         struct during a restore.
+ *       9. Adjust buffer_to_mon() in src/restore.c to properly
+ *     10. Adjust savemonchn() in src/save.c to deal with your
+ *         struct during a save.
+ *     11. Adjust mon_to_buffer() in src/save.c to properly package
+ *         up your struct when the rest of the monst struct is
+ *         packaged up.
+ */
+ 
 #define FCSIZ  (ROWNO+COLNO)
 
 struct fakecorridor {