Address review feedback

src/orange/g4org/ProtoConstructor.cc

@@ -112,15 +112,7 @@ auto ProtoConstructor::operator()(LogicalVolume const& lv) -> SPUnitProto
 
 //---------------------------------------------------------------------------//
 /*!
- * Place this PV into the proto.
- *
- * - proto boundary is already constructed as a parent unit
- * - when inlining a child, we explicitly subtract the children
- * - "top-level" children don't get subtracted; the parent volume has a
- *   "background"
- * - child is inlined if it's only used once; *its* shape needs to have the
- *   children subtracted from it explicitly
- * - child is inlined if it has no children
+ * Place this physical volume into the proto.
  */
 void ProtoConstructor::place_pv(VariantTransform const& parent_transform,
                                 PhysicalVolume const& pv,

src/orange/g4org/ProtoConstructor.hh

@@ -21,7 +21,14 @@ namespace g4org
 {
 //---------------------------------------------------------------------------//
 /*!
- * Build a proto-universe from a logical volume.
+ * Recursively build ORANGE proto-universes from a \c LogicalVolume .
+ *
+ * The input to this function is the output of \c LogicalVolumeConverter . This
+ * class is responsible for "placing" the converted \c PhysicalVolume by
+ * transforming its children. Depending on heuristics, the children are
+ * directly inserted into a \c UnitProto as volumes (specifically, the logical
+ * volume becomes a \c UnitProto::MaterialInput), or a \c LogicalVolume is
+ * turned into a \em new \c UnitProto that can be used in multiple locations.
  */
 class ProtoConstructor
 {
@@ -51,8 +58,8 @@ class ProtoConstructor
                   PhysicalVolume const& pv,
                   ProtoInput* proto);
 
-    // Number of daughters above which we use a "fill" material
-    // TODO: make this configurable
+    // (TODO: make this configurable)
+    //! Number of daughters above which we use a "fill" material
     static constexpr int fill_daughter_threshold() { return 2; }
 };