Commit ebb465e

@@ -1,10 +1,23 @@
 module Saml
   module Kit
+    # This class is used to parse the IDPSSODescriptor from a SAML metadata document.
+    #
+    #  <?xml version="1.0" encoding="UTF-8"?>
+    #  <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_cfa24e2f-0ec0-4ee3-abb8-b2fcfe394c1c" entityID="">
+    #    <IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
+    #      <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://www.example.com/logout"/>
+    #      <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
+    #      <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://www.example.com/login"/>
+    #      <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://www.example.com/login"/>
+    #      <saml:Attribute Name="id"/>
+    #    </IDPSSODescriptor>
+    #  </EntityDescriptor>
     class IdentityProviderMetadata < Metadata
       def initialize(xml)
         super("IDPSSODescriptor", xml)
       end
 
+      # Returns the IDPSSODescriptor/@WantAuthnRequestsSigned attribute.
       def want_authn_requests_signed
         xpath = "/md:EntityDescriptor/md:#{name}"
         attribute = document.find_by(xpath).attribute("WantAuthnRequestsSigned")
@@ -12,14 +25,19 @@ module Saml
         attribute.text.downcase == "true"
       end
 
+      # Returns each of the SingleSignOnService elements.
       def single_sign_on_services
         services('SingleSignOnService')
       end
 
+      # Returns a SingleSignOnService elements with the specified binding.
+      #
+      # @param binding [Symbol] `:http_post` or `:http_redirect`.
       def single_sign_on_service_for(binding:)
         service_for(binding: binding, type: 'SingleSignOnService')
       end
 
+      # Returns each of the Attributes in the metadata.
       def attributes
         document.find_all("/md:EntityDescriptor/md:#{name}/saml:Attribute").map do |item|
           {
@@ -29,7 +47,13 @@ module Saml
         end
       end
 
-      def login_request_for(binding:, relay_state: nil, configuration: Saml::Kit.configuration)
+      # Creates a AuthnRequest document for the specified binding.
+      #
+      # @param binding [Symbol] `:http_post` or `:http_redirect`.
+      # @param relay_state [Object] The RelayState to include the returned SAML params.
+      # @param configuration [Saml::Kit::Configuration] the configuration to use for generating the request.
+      # @return [Array] The url and saml params encoded using the rules for the specified binding.
+      def login_request_for(binding:, relay_state: nil, configuration: Saml::Kit.configuration) # :yields builder
         builder = Saml::Kit::AuthenticationRequest.builder(configuration: configuration) do |x|
           x.embed_signature = want_authn_requests_signed
           yield x if block_given?
@@ -38,10 +62,12 @@ module Saml
         request_binding.serialize(builder, relay_state: relay_state)
       end
 
+      # @!visibility private
       def self.builder_class
         Saml::Kit::Builders::IdentityProviderMetadata
       end
 
+      # @deprecated Use {#Saml::Kit::Builders::IdentityProviderMetadata} instead of this.
       Builder = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('Saml::Kit::IdentityProviderMetadata::Builder', 'Saml::Kit::Builders::IdentityProviderMetadata')
     end
   end