From c063620d937bd622fc8ffb80a70647fedff7a73e Mon Sep 17 00:00:00 2001
From: Philip Helger <philip@helger.com>
Date: Wed, 7 Aug 2024 19:32:57 +0200
Subject: [PATCH] Updated docs

---
 .../smpclient/peppol/SMPClientReadOnly.java   | 43 ++++++++-----------
 .../utils/W3CEndpointReferenceHelper.java     |  4 +-
 2 files changed, 22 insertions(+), 25 deletions(-)

diff --git a/peppol-smp-client/src/main/java/com/helger/smpclient/peppol/SMPClientReadOnly.java b/peppol-smp-client/src/main/java/com/helger/smpclient/peppol/SMPClientReadOnly.java
index 9d2a9e9b..3ffe5cdd 100644
--- a/peppol-smp-client/src/main/java/com/helger/smpclient/peppol/SMPClientReadOnly.java
+++ b/peppol-smp-client/src/main/java/com/helger/smpclient/peppol/SMPClientReadOnly.java
@@ -164,7 +164,10 @@ public SMPClientReadOnly (@Nonnull final URI aSMPHost)
 
   /**
    * Gets a list of references to the CompleteServiceGroup's owned by the
-   * specified userId. This is a non-specification compliant method.
+   * specified userId.<br>
+   * NOTE: this API is NOT supported by all SMP implementations. It is based on
+   * a proprietary API provided by the Peppol reference implementation and now
+   * supported by phoss SMP but not all other SMPs.
    *
    * @param sUserID
    *        The username for which to retrieve service groups.
@@ -208,7 +211,10 @@ public ServiceGroupReferenceListType getServiceGroupReferenceList (@Nonnull fina
 
   /**
    * Gets a list of references to the CompleteServiceGroup's owned by the
-   * specified userId. This is a non-specification compliant method.
+   * specified userId.<br>
+   * NOTE: this API is NOT supported by all SMP implementations. It is based on
+   * a proprietary API provided by the Peppol reference implementation and now
+   * supported by phoss SMP but not all other SMPs.
    *
    * @param sUserID
    *        The username for which to retrieve service groups.
@@ -356,26 +362,6 @@ public CompleteServiceGroupType getCompleteServiceGroupOrNull (@Nonnull final IP
     }
   }
 
-  /**
-   * Returns a service group. A service group references to the service
-   * metadata. This is a specification compliant method.
-   *
-   * @param aServiceGroupID
-   *        The service group id corresponding to the service group which one
-   *        wants to get.
-   * @return The service group. Never <code>null</code>.
-   * @throws SMPClientException
-   *         in case something goes wrong
-   * @throws SMPClientUnauthorizedException
-   *         A HTTP Forbidden was received, should not happen.
-   * @throws SMPClientParticipantNotFoundException
-   *         The service group id does not exist in the network.
-   * @throws SMPClientNotFoundException
-   *         The service group id or document types did not exist.
-   * @throws SMPClientBadRequestException
-   *         The request was not well formed.
-   * @see #getServiceGroupOrNull(IParticipantIdentifier)
-   */
   @Nonnull
   public ServiceGroupType getServiceGroup (@Nonnull final IParticipantIdentifier aServiceGroupID) throws SMPClientException
   {
@@ -422,6 +408,7 @@ public ServiceGroupType getServiceGroupOrNull (@Nonnull final IParticipantIdenti
    * @param aSG
    *        The service group to parse. May be <code>null</code>.
    * @return Never <code>null</code> but a maybe empty list.
+   * @see #getAllDocumentTypes(ServiceGroupType, IIdentifierFactory, Consumer)
    * @since 8.0.4
    */
   @Nonnull
@@ -500,7 +487,8 @@ public static ICommonsList <IDocumentTypeIdentifier> getAllDocumentTypes (@Nulla
 
   /**
    * Gets a signed service metadata object given by its service group id and its
-   * document type. This is a specification compliant method.
+   * document type.<br>
+   * This is a specification compliant method.
    *
    * @param aServiceGroupID
    *        The service group id of the service metadata to get. May not be
@@ -626,7 +614,8 @@ public SignedServiceMetadataType getServiceMetadata (@Nonnull final IParticipant
 
   /**
    * Gets a signed service metadata object given by its service group id and its
-   * document type. This is a specification compliant method.
+   * document type.<br>
+   * This is a specification compliant method.
    *
    * @param aServiceGroupID
    *        The service group id of the service metadata to get. May not be
@@ -684,6 +673,12 @@ private static boolean _hasSameContent (@Nonnull final ProcessIdentifierType aPI
    *        The required transport profile to be used. May not be
    *        <code>null</code>.
    * @return <code>null</code> if no matching endpoint was found
+   * @see #getEndpoint(ServiceMetadataType, IProcessIdentifier,
+   *      ISMPTransportProfile)
+   * @see #getEndpointAt(SignedServiceMetadataType, IProcessIdentifier,
+   *      ISMPTransportProfile, LocalDateTime)
+   * @see #getEndpointAt(ServiceMetadataType, IProcessIdentifier,
+   *      ISMPTransportProfile, LocalDateTime)
    */
   @Nullable
   public static EndpointType getEndpoint (@Nonnull final SignedServiceMetadataType aSignedServiceMetadata,
diff --git a/peppol-smp-client/src/main/java/com/helger/smpclient/peppol/utils/W3CEndpointReferenceHelper.java b/peppol-smp-client/src/main/java/com/helger/smpclient/peppol/utils/W3CEndpointReferenceHelper.java
index a2ea920b..d3573fd8 100644
--- a/peppol-smp-client/src/main/java/com/helger/smpclient/peppol/utils/W3CEndpointReferenceHelper.java
+++ b/peppol-smp-client/src/main/java/com/helger/smpclient/peppol/utils/W3CEndpointReferenceHelper.java
@@ -121,7 +121,9 @@ private static Element _convertReferenceToXML (@Nonnull final W3CEndpointReferen
   }
 
   /**
-   * Get the address contained in the passed endpoint reference.
+   * Get the address contained in the passed endpoint reference.<br>
+   * See https://github.com/jakartaee/jax-ws-api/issues/167 why this is done so
+   * stupidly
    *
    * @param aEndpointReference
    *        The endpoint reference to retrieve the address from. May not be