docs(pipnn): clarify invariants flagged in review

- Note that the IP branch of distance_from_dot must return before the norm
  lookups because norms_ is never allocated for IP.
- Document that group_duplicate_rows deduplicates bitwise on raw row bytes, so
  -0.0f and +0.0f are intentionally distinct.
- Document that odescent_param_->max_degree is mutated in place by the bottom
  graph build, which is pre-existing 1.0 behaviour.

No behaviour change.

Signed-off-by: 庄叶 <zhuangye.yxw@antgroup.com>

Author: lightWantAnt

src/algorithm/hgraph/hgraph_build.cpp

@@ -345,6 +345,11 @@ HGraph::build_by_batch_graph(const DatasetPtr& data, bool use_pipnn) {
             }
         }
     } else {
+        // Note: odescent_param_ is a shared member and this mutates it in place, so
+        // max_degree is left at the bottom-graph degree after this call. That is
+        // pre-existing 1.0 behaviour (the route-graph loop below has always
+        // overwritten the same shared field), and the PiPNN route-graph path copies
+        // the parameter before adjusting it for exactly this reason.
         odescent_param_->max_degree = bottom_graph_->MaximumDegree();
         ODescent odescent_builder(
             odescent_param_, build_data, allocator_, this->thread_pool_.get());

src/impl/pipnn/pipnn_graph_builder.cpp

@@ -156,6 +156,10 @@ group_duplicate_rows(const Vector<InnerIdType>& ids,
     const uint64_t row_bytes = checked_product(dimensions, sizeof(float), "row");
     require_argument(row_bytes <= std::numeric_limits<std::size_t>::max(),
                      "PiPNN row size exceeds the platform limit");
+    // Deduplication is intentionally bitwise: the key is a string_view over the raw
+    // float bytes, so two rows compare equal only when every byte matches. This is what
+    // PiPNN wants (a duplicate vector is one that is identical on disk), and it means
+    // -0.0f and +0.0f are treated as distinct rows rather than being merged.
     UnorderedMap<std::string_view, InnerIdType> representatives(allocator);
     representatives.reserve(rows.size());
 
@@ -1203,8 +1207,11 @@ PiPNNPipeline::distance_from_dot(uint32_t lhs, uint32_t rhs, float dot) const {
         return std::max(0.0F, sanitize_distance(sum - dot - dot));
     }
     if (metric_ == MetricType::METRIC_TYPE_IP) {
+        // norms_ is never allocated for IP (see prepare()), so this branch must
+        // return before the norm lookups below.
         return sanitize_distance(1.0F - dot);
     }
+    // Cosine (and any other norm-normalized metric).
     const float similarity = std::clamp(dot * norms_[lhs] * norms_[rhs], -1.0F, 1.0F);
     return sanitize_distance(1.0F - similarity);
 }