Clarify when estimate methods return empty (#2323)

## Description

Clarifies when estimate methods return an empty optional. This also
fixes some parity issues with Constrained SolvePnP not checking the
optional returned by the heading buffer.

Resolves #2322.

## Meta

Merge checklist:
- [x] Pull Request title is [short, imperative
summary](https://cbea.ms/git-commit/) of proposed changes
- [x] The description documents the _what_ and _why_
- [ ] If this PR changes behavior or adds a feature, user documentation
is updated
- [ ] If this PR touches photon-serde, all messages have been
regenerated and hashes have not changed unexpectedly
- [ ] If this PR touches configuration, this is backwards compatible
with settings back to v2025.3.2
- [ ] If this PR touches pipeline settings or anything related to data
exchange, the frontend typing is updated
- [ ] If this PR addresses a bug, a regression test for it is added

photon-lib/src/main/native/include/photon/PhotonPoseEstimator.h

@@ -294,7 +294,7 @@ class PhotonPoseEstimator {
    *
    * @param cameraResult A pipeline result from the camera.
    * @return An EstimatedRobotPose with an estimated pose, timestamp, and
-   * targets used to create the estimate.
+   * targets used to create the estimate, or std::nullopt if there's no targets.
    */
   std::optional<EstimatedRobotPose> EstimateLowestAmbiguityPose(
       PhotonPipelineResult cameraResult);
@@ -306,7 +306,7 @@ class PhotonPoseEstimator {
    *
    * @param cameraResult A pipeline result from the camera.
    * @return An EstimatedRobotPose with an estimated pose, timestamp and
-   * targets used to create the estimate.
+   * targets used to create the estimate, or std::nullopt if there's no targets.
    */
   std::optional<EstimatedRobotPose> EstimateClosestToCameraHeightPose(
       PhotonPipelineResult cameraResult);
@@ -319,7 +319,7 @@ class PhotonPoseEstimator {
    * @param referencePose reference pose to check vector magnitude difference
    * against.
    * @return An EstimatedRobotPose with an estimated pose, timestamp, and
-   * targets used to create the estimate.
+   * targets used to create the estimate, or std::nullopt if there's no targets.
    */
   std::optional<EstimatedRobotPose> EstimateClosestToReferencePose(
       PhotonPipelineResult cameraResult, frc::Pose3d referencePose);
@@ -331,7 +331,8 @@ class PhotonPoseEstimator {
    *
    * @param cameraResult A pipeline result from the camera.
    * @return An EstimatedRobotPose with an estimated pose, timestamp, and
-   * targets used to create the estimate.
+   * targets used to create the estimate or std::nullopt if there's no targets,
+   * no multi-tag results, or multi-tag is disabled in the web UI.
    */
   std::optional<EstimatedRobotPose> EstimateCoprocMultiTagPose(
       PhotonPipelineResult cameraResult);
@@ -345,7 +346,8 @@ class PhotonPoseEstimator {
    * @param cameraMatrix Camera intrinsics from camera calibration data.
    * @param distCoeffs Distortion coefficients from camera calibration data.
    * @return An EstimatedRobotPose with an estimated pose, timestamp, and
-   * targets used to create the estimate.
+   * targets used to create the estimate, or std::nullopt if there's less than 2
+   * targets visible or SolvePnP fails.
    */
   std::optional<EstimatedRobotPose> EstimateRioMultiTagPose(
       PhotonPipelineResult cameraResult, PhotonCamera::CameraMatrix camMat,
@@ -363,7 +365,8 @@ class PhotonPoseEstimator {
    *
    * @param cameraResult A pipeline result from the camera.
    * @return An EstimatedRobotPose with an estimated pose, timestamp, and
-   * targets used to create the estimate.
+   * targets used to create the estimate, or std::nullopt if there's no targets
+   * or heading data.
    */
   std::optional<EstimatedRobotPose> EstimatePnpDistanceTrigSolvePose(
       PhotonPipelineResult cameraResult);
@@ -372,7 +375,7 @@ class PhotonPoseEstimator {
    * Return the average of the best target poses using ambiguity as weight.
    * @param cameraResult A pipeline result from the camera.
    * @return An EstimatedRobotPose with an estimated pose, timestamp, and
-   * targets used to create the estimate.
+   * targets used to create the estimate, or std::nullopt if there's no targets.
    */
   std::optional<EstimatedRobotPose> EstimateAverageBestTargetsPose(
       PhotonPipelineResult cameraResult);
@@ -401,7 +404,8 @@ class PhotonPoseEstimator {
    * changing our robot heading estimate against the tag corner reprojection
    * error cost.
    * @return An EstimatedRobotPose with an estimated pose, timestamp, and
-   * targets used to create the estimate.
+   * targets used to create the estimate, or std::nullopt if there's no targets
+   * or heading data, or if the solver fails to solve the problem.
    */
   std::optional<EstimatedRobotPose> EstimateConstrainedSolvepnpPose(
       photon::PhotonPipelineResult cameraResult,