rework docs, comments, clean up unnecessary init

docs/changelog.txt

@@ -82,7 +82,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - `Military`: New module for military functionality
 - `Military`: new ``makeSquad`` to create a squad
 - `Military`: changed ``getSquadName`` to take a squad identifier
-- `Military`: new ``updateRoomAssignments`` for assigning a squad to a barracks and archery range- ``Maps::GetBiomeType`` renamed to ``Maps::getBiomeType`` for consistency
+- `Military`: new ``updateRoomAssignments`` for assigning a squad to a barracks and archery range
 - ``Maps::GetBiomeType`` renamed to ``Maps::getBiomeType`` for consistency
 - ``Maps::GetBiomeTypeRef`` renamed to ``Maps::getBiomeTypeRef`` for consistency
 

docs/dev/Lua API.rst

@@ -1594,8 +1594,10 @@ Military module
 
 * ``dfhack.military.makeSquad(assignment_id)``
 
-  Creates a new squad associated with the assignment. Fails if one already exists.
-  Note: This function does not name the squad, but they are otherwise complete.
+  Creates a new squad associated with the assignment (ie df::entity_position_assignment, via `id``) and returns it.
+  Fails if a squad already exists that is associated with that assignment, or if the assignment is not a fort mode player controlled squad.
+  Note: This function does not name the squad: consider setting a nickname (under result.name.nickname), and/or filling out the language_name object at result.name.
+  The returned squad is otherwise complete and requires no more setup to work correctly.
 
 * ``dfhack.military.updateRoomAssignments(squad_id, assignment_id, squad_use_flags)``
 
@@ -1603,7 +1605,7 @@ Military module
 
 * ``dfhack.military.getSquadName(squad_id)``
 
-  Returns the name of a squad.
+  Returns the name of a squad as a string.
 
 Action Timer API
 ~~~~~~~~~~~~~~~~

library/modules/Military.cpp

@@ -84,16 +84,13 @@ df::squad* Military::makeSquad(int32_t assignment_id)
 
     df::squad* result = new df::squad();
     result->id = *df::global::squad_next_id;
-    result->cur_routine_idx = 0;
     result->uniform_priority = result->id + 1; //no idea why, but seems to hold
-    result->activity = -1; //??
     result->carry_food = 2;
     result->carry_water = 1;
     result->entity_id = df::global::plotinfo->group_id;
     result->leader_position = corresponding_position->id;
     result->leader_assignment = found_assignment->id;
     result->name = name;
-    result->ammo.update = 0;
 
     int16_t squad_size = corresponding_position->squad_size;
 
@@ -143,7 +140,7 @@ df::squad* Military::makeSquad(int32_t assignment_id)
             asched[month].uniform_mode = 0;
         };
 
-        //I thought this was a terrible hack, but its literally how dwarf fortress does it 1:1
+        //Dwarf fortress does do this via a series of string comparisons
         //Off duty: No orders, Sleep/room at will. Equip/orders only
         if (routine->name == "Off duty")
         {
@@ -153,8 +150,7 @@ df::squad* Military::makeSquad(int32_t assignment_id)
                 asched[i].uniform_mode = 1;
             }
         }
-        //Staggered Training: Training orders at 3 4 5, 9 10 11, sleep/room at will. Equip/orders only, except train months which are equip/always
-        //always seen the training indices 0 1 2 6 7 8, so its unclear. Check if squad id matters
+        //Staggered Training: Training orders at months 3 4 5 9 10 11, *or* 0 1 2 6 7 8, sleep/room at will. Equip/orders only, except train months which are equip/always
         else if (routine->name == "Staggered training")
         {
             //this is semi randomised for different squads
@@ -209,15 +205,12 @@ df::squad* Military::makeSquad(int32_t assignment_id)
         result->schedule.push_back(reinterpret_cast<df::squad::T_schedule*>(asched));
     }
 
-    //all we've done so far is leak memory if anything goes wrong
-    //modify state
+    //Modify necessary world state
     (*df::global::squad_next_id)++;
     fort->squads.push_back(result->id);
     df::global::world->squads.all.push_back(result);
     found_assignment->squad_id = result->id;
 
-    //todo: find and modify old squad
-
     return result;
 }