OSDN Git Service

Add Doxygen comment to grid.c.
[hengband/hengband.git] / src / grid.c
index 12b02ef..6612d54 100644 (file)
@@ -1,14 +1,15 @@
-/*
- * File: grid.c
- * Purpose: low-level dungeon creation primitives
- */
-
-/*
- * Copyright (c) 1997 Ben Harrison, James E. Wilson, Robert A. Koeneke
- *
- * This software may be copied and distributed for educational, research,
- * and not for profit purposes provided that this copyright and statement
- * are included in all such copies.  Other copyrights may also apply.
+/*!
+ * @file grid.c
+ * @brief ¥À¥ó¥¸¥ç¥ó¤ÎÀ¸À®½èÍý¤Î´ð´´Éôʬ / low-level dungeon creation primitives
+ * @date 2014/01/04
+ * @author
+ * Copyright (c) 1997 Ben Harrison, James E. Wilson, Robert A. Koeneke\n
+ *\n
+ * This software may be copied and distributed for educational, research,\n
+ * and not for profit purposes provided that this copyright and statement\n
+ * are included in all such copies.  Other copyrights may also apply.\n
+ * \n
+ * 2014 Deskull Doxygen¸þ¤±¤Î¥³¥á¥ó¥ÈÀ°Íý\n
  */
 
 #include "angband.h"
@@ -16,8 +17,9 @@
 #include "grid.h"
 
 
-/*
- * Returns random co-ordinates for player/monster/object
+/*!
+ * @brief ¿·µ¬¥Õ¥í¥¢¤ËÆþ¤ê¤¿¤Æ¤Î¥×¥ì¥¤¥ä¡¼¤ò¥é¥ó¥À¥à¤Ê¾ì½ê¤ËÇÛÃÖ¤¹¤ë / Returns random co-ordinates for player/monster/object
+ * @return ÇÛÃÖ¤ËÀ®¸ù¤·¤¿¤éTRUE¤òÊÖ¤¹
  */
 bool new_player_spot(void)
 {
@@ -76,8 +78,12 @@ bool new_player_spot(void)
 }
 
 
-/*
- * Place an up/down staircase at given location
+
+/*!
+ * @brief ½êÄê¤Î°ÌÃ֤˾å¤ê³¬Ãʤ«²¼¤ê³¬ÃʤòÇÛÃÖ¤¹¤ë / Place an up/down staircase at given location
+ * @param y ÇÛÃÖ¤ò»î¤ß¤¿¤¤¥Þ¥¹¤ÎYºÂɸ
+ * @param x ÇÛÃÖ¤ò»î¤ß¤¿¤¤¥Þ¥¹¤ÎXºÂɸ
+ * @return ¤Ê¤·
  */
 void place_random_stairs(int y, int x)
 {
@@ -122,19 +128,19 @@ void place_random_stairs(int y, int x)
                place_down_stairs(y, x);
 }
 
-
-/*
- * Place a random type of door at the given location
+/*!
+ * @brief ½êÄê¤Î°ÌÃ֤ˤµ¤Þ¤¶¤Þ¤Ê¾õÂÖ¤ä¼ïÎà¤Î¥É¥¢¤òÇÛÃÖ¤¹¤ë / Place a random type of door at the given location
+ * @param y ¥É¥¢¤ÎÇÛÃÖ¤ò»î¤ß¤¿¤¤¥Þ¥¹¤ÎYºÂɸ
+ * @param x ¥É¥¢¤ÎÇÛÃÖ¤ò»î¤ß¤¿¤¤¥Þ¥¹¤ÎXºÂɸ
+ * @param room Éô²°¤ËÀܤ·¤Æ¤¤¤ë¾ì¹ç¸þ¤±¤Î¥É¥¢À¸À®¤«Èݤ«
+ * @return ¤Ê¤·
  */
 void place_random_door(int y, int x, bool room)
 {
-       int tmp;
+       int tmp, type;
        s16b feat = feat_none;
        cave_type *c_ptr = &cave[y][x];
 
-       int type = ((d_info[dungeon_type].flags1 & DF1_CURTAIN) &&
-               one_in_((d_info[dungeon_type].flags1 & DF1_NO_CAVE) ? 16 : 256)) ? DOOR_CURTAIN : DOOR_DOOR;
-
        /* Initialize mimic info */
        c_ptr->mimic = 0;
 
@@ -144,6 +150,10 @@ void place_random_door(int y, int x, bool room)
                return;
        }
 
+       type = ((d_info[dungeon_type].flags1 & DF1_CURTAIN) &&
+               one_in_((d_info[dungeon_type].flags1 & DF1_NO_CAVE) ? 16 : 256)) ? DOOR_CURTAIN :
+               ((d_info[dungeon_type].flags1 & DF1_GLASS_DOOR) ? DOOR_GLASS_DOOR : DOOR_DOOR);
+
        /* Choose an object */
        tmp = randint0(1000);
 
@@ -202,9 +212,12 @@ void place_random_door(int y, int x, bool room)
        delete_monster(y, x);
 }
 
-
-/*
- * Place a random type of normal door at the given location.
+/*!
+ * @brief ½êÄê¤Î°ÌÃ֤˳Ƽï¤ÎÊĤ¸¤¿¥É¥¢¤òÇÛÃÖ¤¹¤ë / Place a random type of normal door at the given location.
+ * @param y ¥É¥¢¤ÎÇÛÃÖ¤ò»î¤ß¤¿¤¤¥Þ¥¹¤ÎYºÂɸ
+ * @param x ¥É¥¢¤ÎÇÛÃÖ¤ò»î¤ß¤¿¤¤¥Þ¥¹¤ÎXºÂɸ
+ * @param type ¥É¥¢¤ÎÃÏ·ÁID
+ * @return ¤Ê¤·
  */
 void place_closed_door(int y, int x, int type)
 {
@@ -254,9 +267,14 @@ void place_closed_door(int y, int x, int type)
        }
 }
 
-
-/*
- * Make an empty square floor, for the middle of rooms
+/*!
+ * @brief Ä¹Êý·Á¤Î¶õƶ¤òÀ¸À®¤¹¤ë / Make an empty square floor, for the middle of rooms
+ * @param x1 Ä¹Êý·Á¤Îº¸Ã¼XºÂɸ(-1)
+ * @param x2 Ä¹Êý·Á¤Î±¦Ã¼XºÂɸ(+1)
+ * @param y1 Ä¹Êý·Á¤Î¾åüYºÂɸ(-1)
+ * @param y2 Ä¹Êý·Á¤Î²¼Ã¼YºÂɸ(+1)
+ * @param light ¾ÈÌÀ¤Î̵ͭ
+ * @return ¤Ê¤·
  */
 void place_floor(int x1, int x2, int y1, int y2, bool light)
 {
@@ -275,8 +293,14 @@ void place_floor(int x1, int x2, int y1, int y2, bool light)
 }
 
 
-/*
- * Make an empty square room, only floor and wall grids
+/*!
+ * @brief Ä¹Êý·Á¤ÎÉô²°¤òÀ¸À®¤¹¤ë / Make an empty square room, only floor and wall grids
+ * @param x1 Ä¹Êý·Á¤Îº¸Ã¼XºÂɸ(-1)
+ * @param x2 Ä¹Êý·Á¤Î±¦Ã¼XºÂɸ(+1)
+ * @param y1 Ä¹Êý·Á¤Î¾åüYºÂɸ(-1)
+ * @param y2 Ä¹Êý·Á¤Î²¼Ã¼YºÂɸ(+1)
+ * @param light ¾ÈÌÀ¤Î̵ͭ
+ * @return ¤Ê¤·
  */
 void place_room(int x1, int x2, int y1, int y2, bool light)
 {
@@ -298,8 +322,13 @@ void place_room(int x1, int x2, int y1, int y2, bool light)
 }
 
 
-/*
- * Create up to "num" objects near the given coordinates
+/*!
+ * @brief Æüì¤ÊÉô²°¸þ¤±¤Ë³Æ¼ï¥¢¥¤¥Æ¥à¤òÇÛÃÖ¤¹¤ë / Create up to "num" objects near the given coordinates
+ * @param y ÇÛÃÖ¤·¤¿¤¤Ãæ¿´¥Þ¥¹¤ÎYºÂɸ
+ * @param x ÇÛÃÖ¤·¤¿¤¤Ãæ¿´¥Þ¥¹¤ÎXºÂɸ
+ * @param num ÇÛÃÖ¤·¤¿¤¤¿ô
+ * @return ¤Ê¤·
+ * @details
  * Only really called by some of the "vault" routines.
  */
 void vault_objects(int y, int x, int num)
@@ -363,9 +392,15 @@ msg_print("
        }
 }
 
-
-/*
- * Place a trap with a given displacement of point
+/*!
+ * @brief Æüì¤ÊÉô²°¸þ¤±¤Ë³Æ¼ï¥¢¥¤¥Æ¥à¤òÇÛÃÖ¤¹¤ë(vault_trap¤Î¥µ¥Ö¥»¥Ã¥È) / Place a trap with a given displacement of point
+ * @param y ¥È¥é¥Ã¥×¤òÇÛÃÖ¤·¤¿¤¤¥Þ¥¹¤ÎÃæ¿´YºÂɸ
+ * @param x ¥È¥é¥Ã¥×¤òÇÛÃÖ¤·¤¿¤¤¥Þ¥¹¤ÎÃæ¿´XºÂɸ
+ * @param yd YÊý¸þ¤ÎÇÛÃÖʬ»¶¥Þ¥¹¿ô
+ * @param xd XÊý¸þ¤ÎÇÛÃÖʬ»¶¥Þ¥¹¿ô
+ * @return ¤Ê¤·
+ * @details
+ * Only really called by some of the "vault" routines.
  */
 void vault_trap_aux(int y, int x, int yd, int xd)
 {
@@ -412,9 +447,16 @@ msg_print("
        }
 }
 
-
-/*
- * Place some traps with a given displacement of given location
+/*!
+ * @brief Æüì¤ÊÉô²°¸þ¤±¤Ë³Æ¼ï¥¢¥¤¥Æ¥à¤òÇÛÃÖ¤¹¤ë(¥á¥¤¥ó¥ë¡¼¥Á¥ó) / Place some traps with a given displacement of given location
+ * @param y ¥È¥é¥Ã¥×¤òÇÛÃÖ¤·¤¿¤¤¥Þ¥¹¤ÎÃæ¿´YºÂɸ
+ * @param x ¥È¥é¥Ã¥×¤òÇÛÃÖ¤·¤¿¤¤¥Þ¥¹¤ÎÃæ¿´XºÂɸ
+ * @param yd YÊý¸þ¤ÎÇÛÃÖʬ»¶¥Þ¥¹¿ô
+ * @param xd XÊý¸þ¤ÎÇÛÃÖʬ»¶¥Þ¥¹¿ô
+ * @param num ÇÛÃÖ¤·¤¿¤¤¥È¥é¥Ã¥×¤Î¿ô
+ * @return ¤Ê¤·
+ * @details
+ * Only really called by some of the "vault" routines.
  */
 void vault_traps(int y, int x, int yd, int xd, int num)
 {
@@ -426,9 +468,14 @@ void vault_traps(int y, int x, int yd, int xd, int num)
        }
 }
 
-
-/*
- * Hack -- Place some sleeping monsters near the given location
+/*!
+ * @brief Æüì¤ÊÉô²°ÃÏ·Á¸þ¤±¤Ë¥â¥ó¥¹¥¿¡¼¤òÇÛÃÖ¤¹¤ë / Hack -- Place some sleeping monsters near the given location
+ * @param y1 ¥â¥ó¥¹¥¿¡¼¤òÇÛÃÖ¤·¤¿¤¤¥Þ¥¹¤ÎÃæ¿´YºÂɸ
+ * @param x1 ¥â¥ó¥¹¥¿¡¼¤òÇÛÃÖ¤·¤¿¤¤¥Þ¥¹¤ÎÃæ¿´XºÂɸ
+ * @param num ÇÛÃÖ¤·¤¿¤¤¥â¥ó¥¹¥¿¡¼¤Î¿ô
+ * @return ¤Ê¤·
+ * @details
+ * Only really called by some of the "vault" routines.
  */
 void vault_monsters(int y1, int x1, int num)
 {
@@ -459,8 +506,15 @@ void vault_monsters(int y1, int x1, int num)
 }
 
 
-/*
- * Always picks a correct direction
+/*!
+ * @brief build_tunnelÍѤËÄÌÏ©¤ò·¡¤ë¤¿¤á¤ÎÊý¸þ¤ò°ÌÃÖ´Ø·¸Ä̤ê¤Ë·è¤á¤ë / Always picks a correct direction
+ * @param rdir YÊý¸þ¤Ë¼è¤ë¤Ù¤­¥Ù¥¯¥È¥ëÃͤòÊÖ¤¹»²¾È¥Ý¥¤¥ó¥¿
+ * @param cdir XÊý¸þ¤Ë¼è¤ë¤Ù¤­¥Ù¥¯¥È¥ëÃͤòÊÖ¤¹»²¾È¥Ý¥¤¥ó¥¿
+ * @param y1 »ÏÅÀYºÂɸ
+ * @param x1 »ÏÅÀXºÂɸ
+ * @param y2 ½ªÅÀYºÂɸ
+ * @param x2 ½ªÅÀXºÂɸ
+ * @return ¤Ê¤·
  */
 void correct_dir(int *rdir, int *cdir, int y1, int x1, int y2, int x2)
 {
@@ -478,9 +532,11 @@ void correct_dir(int *rdir, int *cdir, int y1, int x1, int y2, int x2)
        }
 }
 
-
-/*
- * Pick a random direction
+/*!
+ * @brief build_tunnelÍѤËÄÌÏ©¤ò·¡¤ë¤¿¤á¤ÎÊý¸þ¤ò¥é¥ó¥À¥à¤Ë·è¤á¤ë / Pick a random direction
+ * @param rdir YÊý¸þ¤Ë¼è¤ë¤Ù¤­¥Ù¥¯¥È¥ëÃͤòÊÖ¤¹»²¾È¥Ý¥¤¥ó¥¿
+ * @param cdir XÊý¸þ¤Ë¼è¤ë¤Ù¤­¥Ù¥¯¥È¥ëÃͤòÊÖ¤¹»²¾È¥Ý¥¤¥ó¥¿
+ * @return ¤Ê¤·
  */
 void rand_dir(int *rdir, int *cdir)
 {
@@ -492,8 +548,12 @@ void rand_dir(int *rdir, int *cdir)
        *cdir = ddx_ddd[i];
 }
 
-
-/* Function that sees if a square is a floor.  (Includes range checking.) */
+/*!
+ * @brief »ØÄê¤Î¥Þ¥¹¤¬¾²·ÏÃÏ·Á¤Ç¤¢¤ë¤«¤òÊÖ¤¹ / Function that sees if a square is a floor.  (Includes range checking.)
+ * @param x ¥Á¥§¥Ã¥¯¤¹¤ë¥Þ¥¹¤ÎXºÂɸ
+ * @param y ¥Á¥§¥Ã¥¯¤¹¤ë¥Þ¥¹¤ÎYºÂɸ
+ * @return ¾²·ÏÃÏ·Á¤Ê¤é¤ÐTRUE
+ */
 bool get_is_floor(int x, int y)
 {
        if (!in_bounds(y, x))
@@ -508,8 +568,12 @@ bool get_is_floor(int x, int y)
        return (FALSE);
 }
 
-
-/* Set a square to be floor.  (Includes range checking.) */
+/*!
+ * @brief »ØÄê¤Î¥Þ¥¹¤ò¾²ÃÏ·Á¤ËÊѤ¨¤ë / Set a square to be floor.  (Includes range checking.)
+ * @param x ÃÏ·Á¤òÊѤ¨¤¿¤¤¥Þ¥¹¤ÎXºÂɸ
+ * @param y ÃÏ·Á¤òÊѤ¨¤¿¤¤¥Þ¥¹¤ÎYºÂɸ
+ * @return ¤Ê¤·
+ */
 void set_floor(int x, int y)
 {
        if (!in_bounds(y, x))
@@ -530,38 +594,42 @@ void set_floor(int x, int y)
 }
 
 
-
-/*
- * Constructs a tunnel between two points
- *
- * This function must be called BEFORE any streamers are created,
- * since we use the special "granite wall" sub-types to keep track
- * of legal places for corridors to pierce rooms.
- *
- * We use "door_flag" to prevent excessive construction of doors
- * along overlapping corridors.
- *
- * We queue the tunnel grids to prevent door creation along a corridor
- * which intersects itself.
- *
- * We queue the wall piercing grids to prevent a corridor from leaving
- * a room and then coming back in through the same entrance.
- *
- * We "pierce" grids which are "outer" walls of rooms, and when we
- * do so, we change all adjacent "outer" walls of rooms into "solid"
- * walls so that no two corridors may use adjacent grids for exits.
- *
- * The "solid" wall check prevents corridors from "chopping" the
- * corners of rooms off, as well as "silly" door placement, and
- * "excessively wide" room entrances.
- *
- * Kind of walls:
- *   extra -- walls
- *   inner -- inner room walls
- *   outer -- outer room walls
- *   solid -- solid room walls
+/*!
+ * @brief Éô²°´Ö¤Î¥È¥ó¥Í¥ë¤òÀ¸À®¤¹¤ë / Constructs a tunnel between two points
+ * @param row1 »ÏÅÀYºÂɸ
+ * @param col1 »ÏÅÀXºÂɸ
+ * @param row2 ½ªÅÀYºÂɸ
+ * @param col2 ½ªÅÀXºÂɸ
+ * @return À¸À®¤ËÀ®¸ù¤·¤¿¤éTRUE¤òÊÖ¤¹
+ * @details
+ * This function must be called BEFORE any streamers are created,\n
+ * since we use the special "granite wall" sub-types to keep track\n
+ * of legal places for corridors to pierce rooms.\n
+ *\n
+ * We use "door_flag" to prevent excessive construction of doors\n
+ * along overlapping corridors.\n
+ *\n
+ * We queue the tunnel grids to prevent door creation along a corridor\n
+ * which intersects itself.\n
+ *\n
+ * We queue the wall piercing grids to prevent a corridor from leaving\n
+ * a room and then coming back in through the same entrance.\n
+ *\n
+ * We "pierce" grids which are "outer" walls of rooms, and when we\n
+ * do so, we change all adjacent "outer" walls of rooms into "solid"\n
+ * walls so that no two corridors may use adjacent grids for exits.\n
+ *\n
+ * The "solid" wall check prevents corridors from "chopping" the\n
+ * corners of rooms off, as well as "silly" door placement, and\n
+ * "excessively wide" room entrances.\n
+ *\n
+ * Kind of walls:\n
+ *   extra -- walls\n
+ *   inner -- inner room walls\n
+ *   outer -- outer room walls\n
+ *   solid -- solid room walls\n
  */
-void build_tunnel(int row1, int col1, int row2, int col2)
+bool build_tunnel(int row1, int col1, int row2, int col2)
 {
        int y, x;
        int tmp_row, tmp_col;
@@ -584,7 +652,7 @@ void build_tunnel(int row1, int col1, int row2, int col2)
        while ((row1 != row2) || (col1 != col2))
        {
                /* Mega-Hack -- Paranoia -- prevent infinite loops */
-               if (main_loop_count++ > 2000) break;
+               if (main_loop_count++ > 2000) return FALSE;
 
                /* Allow bends in the tunnel */
                if (randint0(100) < dun_tun_chg)
@@ -625,12 +693,6 @@ void build_tunnel(int row1, int col1, int row2, int col2)
                /* Access the location */
                c_ptr = &cave[tmp_row][tmp_col];
 
-               if (permanent_wall(&f_info[c_ptr->feat]))
-               {
-                       /* Avoid the edge of vaults */
-                       if (is_inner_grid(c_ptr)) continue;
-               }
-
                /* Avoid "solid" walls */
                if (is_solid_grid(c_ptr)) continue;
 
@@ -656,6 +718,7 @@ void build_tunnel(int row1, int col1, int row2, int col2)
                                dun->wall[dun->wall_n].x = col1;
                                dun->wall_n++;
                        }
+                       else return FALSE;
 
                        /* Forbid re-entry near this piercing */
                        for (y = row1 - 1; y <= row1 + 1; y++)
@@ -694,6 +757,7 @@ void build_tunnel(int row1, int col1, int row2, int col2)
                                dun->tunn[dun->tunn_n].x = col1;
                                dun->tunn_n++;
                        }
+                       else return FALSE;
 
                        /* Allow door in next grid */
                        door_flag = FALSE;
@@ -716,6 +780,7 @@ void build_tunnel(int row1, int col1, int row2, int col2)
                                        dun->door[dun->door_n].x = col1;
                                        dun->door_n++;
                                }
+                               else return FALSE;
 
                                /* No door in next grid */
                                door_flag = TRUE;
@@ -737,19 +802,28 @@ void build_tunnel(int row1, int col1, int row2, int col2)
                        }
                }
        }
+
+       return TRUE;
 }
 
 
-/*
- * This routine adds the square to the tunnel
- * It also checks for SOLID walls - and returns a nearby
- * non-SOLID square in (x,y) so that a simple avoiding
- * routine can be used. The returned boolean value reflects
- * whether or not this routine hit a SOLID wall.
- *
- * "affectwall" toggles whether or not this new square affects
- * the boundaries of rooms. - This is used by the catacomb
- * routine.
+/*!
+ * @brief ¥È¥ó¥Í¥ëÀ¸À®¤Î¤¿¤á¤Î´ð½àÅÀ¤ò»ØÄꤹ¤ë¡£
+ * @param x ´ð½àÅÀ¤ò»ØÄꤹ¤ëXºÂɸ¤Î»²¾È¥Ý¥¤¥ó¥¿¡¢Å¬»þÃͤ¬½¤Àµ¤µ¤ì¤ë¡£
+ * @param y ´ð½àÅÀ¤ò»ØÄꤹ¤ëYºÂɸ¤Î»²¾È¥Ý¥¤¥ó¥¿¡¢Å¬»þÃͤ¬½¤Àµ¤µ¤ì¤ë¡£
+ * @param affectwall (Ä´ººÃæ)
+ * @return ¤Ê¤·
+ * @details
+ * This routine adds the square to the tunnel\n
+ * It also checks for SOLID walls - and returns a nearby\n
+ * non-SOLID square in (x,y) so that a simple avoiding\n
+ * routine can be used. The returned boolean value reflects\n
+ * whether or not this routine hit a SOLID wall.\n
+ *\n
+ * "affectwall" toggles whether or not this new square affects\n
+ * the boundaries of rooms. - This is used by the catacomb\n
+ * routine.\n
+ * @todo Æä˾ܺ٤ʽèÍý¤Î°ÕÌ£¤òÄ´ºº¤¹¤Ù¤·
  */
 static bool set_tunnel(int *x, int *y, bool affectwall)
 {
@@ -772,9 +846,10 @@ static bool set_tunnel(int *x, int *y, bool affectwall)
                        dun->tunn[dun->tunn_n].y = *y;
                        dun->tunn[dun->tunn_n].x = *x;
                        dun->tunn_n++;
-               }
 
-               return TRUE;
+                       return TRUE;
+               }
+               else return FALSE;
        }
 
        if (is_floor_bold(*y, *x))
@@ -792,6 +867,7 @@ static bool set_tunnel(int *x, int *y, bool affectwall)
                        dun->wall[dun->wall_n].x = *x;
                        dun->wall_n++;
                }
+               else return FALSE;
 
                /* Forbid re-entry near this piercing */
                for (j = *y - 1; j <= *y + 1; j++)
@@ -858,8 +934,12 @@ static bool set_tunnel(int *x, int *y, bool affectwall)
 }
 
 
-/*
- * This routine creates the catacomb-like tunnels by removing extra rock.
+/*!
+ * @brief ³°Êɤòºï¤Ã¤Æ¡Ö¥«¥¿¥³¥ó¥Ù¾õ¡×¤ÎÄÌÏ©¤òºîÀ®¤¹¤ë / This routine creates the catacomb-like tunnels by removing extra rock.
+ * @param x ´ð½àÅÀ¤ÎXºÂɸ
+ * @param y ´ð½àÅÀ¤ÎYºÂɸ
+ * @return ¤Ê¤·
+ * @details
  * Note that this routine is only called on "even" squares - so it gives
  * a natural checkerboard pattern.
  */
@@ -886,24 +966,27 @@ static void create_cata_tunnel(int x, int y)
 }
 
 
-/*
- * This routine does the bulk of the work in creating the new types of tunnels.
- * It is designed to use very simple algorithms to go from (x1,y1) to (x2,y2)
- * It doesn't need to add any complexity - straight lines are fine.
- * The SOLID walls are avoided by a recursive algorithm which tries random ways
- * around the obstical until it works.  The number of itterations is counted, and it
- * this gets too large the routine exits. This should stop any crashes - but may leave
- * small gaps in the tunnel where there are too many SOLID walls.
- *
- * Type 1 tunnels are extremely simple - straight line from A to B.  This is only used
- * as a part of the dodge SOLID walls algorithm.
- *
- * Type 2 tunnels are made of two straight lines at right angles. When this is used with
- * short line segments it gives the "cavelike" tunnels seen deeper in the dungeon.
- *
- * Type 3 tunnels are made of two straight lines like type 2, but with extra rock removed.
- * This, when used with longer line segments gives the "catacomb-like" tunnels seen near
- * the surface.
+/*!
+ * @brief ¥È¥ó¥Í¥ëÀ¸À®½èÍý¡Ê¾ÜºÙÄ´ººÃæ¡Ë/ This routine does the bulk of the work in creating the new types of tunnels.
+ * @return ¤Ê¤·
+ * @todo ¾ÜºÙÍÑÄ´ºº
+ * @details
+ * It is designed to use very simple algorithms to go from (x1,y1) to (x2,y2)\n
+ * It doesn't need to add any complexity - straight lines are fine.\n
+ * The SOLID walls are avoided by a recursive algorithm which tries random ways\n
+ * around the obstical until it works.  The number of itterations is counted, and it\n
+ * this gets too large the routine exits. This should stop any crashes - but may leave\n
+ * small gaps in the tunnel where there are too many SOLID walls.\n
+ *\n
+ * Type 1 tunnels are extremely simple - straight line from A to B.  This is only used\n
+ * as a part of the dodge SOLID walls algorithm.\n
+ *\n
+ * Type 2 tunnels are made of two straight lines at right angles. When this is used with\n
+ * short line segments it gives the "cavelike" tunnels seen deeper in the dungeon.\n
+ *\n
+ * Type 3 tunnels are made of two straight lines like type 2, but with extra rock removed.\n
+ * This, when used with longer line segments gives the "catacomb-like" tunnels seen near\n
+ * the surface.\n
  */
 static void short_seg_hack(int x1, int y1, int x2, int y2, int type, int count, bool *fail)
 {
@@ -1018,16 +1101,19 @@ static void short_seg_hack(int x1, int y1, int x2, int y2, int type, int count,
 }
 
 
-/*
- * This routine maps a path from (x1, y1) to (x2, y2) avoiding SOLID walls.
- * Permanent rock is ignored in this path finding- sometimes there is no
- * path around anyway -so there will be a crash if we try to find one.
- * This routine is much like the river creation routine in Zangband.
- * It works by dividing a line segment into two.  The segments are divided
- * until they are less than "cutoff" - when the corresponding routine from
- * "short_seg_hack" is called.
- * Note it is VERY important that the "stop if hit another passage" logic
- * stays as is.  Without this the dungeon turns into Swiss Cheese...
+/*!
+ * @brief ÆÃÄê¤ÎÊÉ(±Êµ×ÊɤʤÉ)¤òÈò¤±¤Ê¤¬¤éÉô²°´Ö¤ÎÄÌÏ©¤òºîÀ®¤¹¤ë / This routine maps a path from (x1, y1) to (x2, y2) avoiding SOLID walls.
+ * @return ¤Ê¤·
+ * @todo ¾ÜºÙÍÑÄ´ºº
+ * @details
+ * Permanent rock is ignored in this path finding- sometimes there is no\n
+ * path around anyway -so there will be a crash if we try to find one.\n
+ * This routine is much like the river creation routine in Zangband.\n
+ * It works by dividing a line segment into two.  The segments are divided\n
+ * until they are less than "cutoff" - when the corresponding routine from\n
+ * "short_seg_hack" is called.\n
+ * Note it is VERY important that the "stop if hit another passage" logic\n
+ * stays as is.  Without this the dungeon turns into Swiss Cheese...\n
  */
 bool build_tunnel2(int x1, int y1, int x2, int y2, int type, int cutoff)
 {
@@ -1119,6 +1205,7 @@ bool build_tunnel2(int x1, int y1, int x2, int y2, int type, int cutoff)
                                                dun->door[dun->door_n].x = x3;
                                                dun->door_n++;
                                        }
+                                       else return FALSE;
                                }
                                firstsuccede = TRUE;
                        }