Fix some Endpoint::doc field usages && Rename it to documentation…

… to avoid this kind of mistake in the future (#3044)

zio-http-cli/src/main/scala/zio/http/endpoint/cli/CliEndpoint.scala

@@ -78,8 +78,8 @@ private[cli] object CliEndpoint {
     endpoint: Endpoint[P, In, Err, Out, _],
     getInput: Boolean = true,
   ): CliEndpoint =
-    if (getInput) fromCodec(endpoint.input) ?? endpoint.doc
-    else fromCodec(endpoint.output) ?? endpoint.doc
+    if (getInput) fromCodec(endpoint.input) ?? endpoint.documentation
+    else fromCodec(endpoint.output) ?? endpoint.documentation
 
   def fromCodec[Input](input: HttpCodec[_, Input]): CliEndpoint = {
     input match {

zio-http/shared/src/main/scala/zio/http/endpoint/Endpoint.scala

@@ -54,7 +54,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
   output: HttpCodec[HttpCodecType.ResponseType, Output],
   error: HttpCodec[HttpCodecType.ResponseType, Err],
   codecError: HttpCodec[HttpCodecType.ResponseType, HttpCodecError],
-  doc: Doc,
+  documentation: Doc,
   authType: Auth,
 ) { self =>
 
@@ -74,7 +74,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
    * Returns a new API that is derived from this one, but which includes
    * additional documentation that will be included in OpenAPI generation.
    */
-  def ??(that: Doc): Endpoint[PathInput, Input, Err, Output, Auth] = copy(doc = self.doc + that)
+  def ??(that: Doc): Endpoint[PathInput, Input, Err, Output, Auth] = copy(documentation = self.documentation + that)
 
   /**
    * Flattens out this endpoint to a chunk of alternatives. Each alternative is
@@ -454,7 +454,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output,
       error,
       codecError,
-      doc,
+      documentation,
       authType,
     )
 
@@ -471,7 +471,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output,
       error,
       codecError,
-      self.doc,
+      documentation,
       authType,
     )
 
@@ -488,7 +488,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output,
       error,
       codecError,
-      doc,
+      documentation,
       authType,
     )
 
@@ -505,7 +505,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output,
       error,
       codecError,
-      self.doc,
+      documentation,
       authType,
     )
 
@@ -522,7 +522,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = (HttpCodec.content[Output2] ++ StatusCodec.status(Status.Ok)) | self.output,
       error,
       codecError,
-      doc,
+      documentation,
       authType,
     )
 
@@ -557,7 +557,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = (HttpCodec.content[Output2] ++ StatusCodec.status(status)) | self.output,
       error,
       codecError,
-      doc,
+      documentation,
       authType,
     )
 
@@ -575,7 +575,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = ((HttpCodec.content[Output2] ++ StatusCodec.status(status)) ?? doc) | self.output,
       error,
       codecError,
-      Doc.empty,
+      documentation,
       authType,
     )
 
@@ -593,7 +593,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = (HttpCodec.content[Output2](mediaType) ++ StatusCodec.Ok ?? doc) | self.output,
       error,
       codecError,
-      doc,
+      documentation,
       authType,
     )
 
@@ -612,7 +612,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = ((HttpCodec.content[Output2](mediaType) ++ StatusCodec.status(status)) ?? doc) | self.output,
       error,
       codecError,
-      doc,
+      documentation,
       authType,
     )
 
@@ -630,7 +630,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = (HttpCodec.content[Output2](mediaType) ++ StatusCodec.status(status)) | self.output,
       error,
       codecError,
-      doc,
+      documentation,
       authType,
     )
 
@@ -695,7 +695,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = (contentCodec ++ StatusCodec.status(Status.Ok)) | self.output,
       error,
       codecError,
-      doc,
+      documentation,
       authType,
     )
   }
@@ -719,7 +719,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = (contentCodec ++ StatusCodec.status(Status.Ok) ?? doc) | self.output,
       error,
       codecError,
-      self.doc,
+      documentation,
       authType,
     )
   }
@@ -743,7 +743,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = (contentCodec ++ StatusCodec.status(status) ?? doc) | self.output,
       error,
       codecError,
-      self.doc,
+      documentation,
       authType,
     )
   }
@@ -779,7 +779,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = (contentCodec ++ StatusCodec.status(status)) | self.output,
       error,
       codecError,
-      self.doc,
+      documentation,
       authType,
     )
   }
@@ -797,7 +797,7 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
       output = ((contentCodec ++ StatusCodec.status(status)) ?? doc) | self.output,
       error,
       codecError,
-      self.doc,
+      documentation,
       authType,
     )
   }
@@ -815,12 +815,12 @@ final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
    * example to group endpoints for OpenAPI.
    */
   def tag(tag: String, tags: String*): Endpoint[PathInput, Input, Err, Output, Auth] =
-    copy(doc = doc.tag(tag +: tags))
+    copy(documentation = documentation.tag(tag +: tags))
 
   /**
    * A list of tags for this endpoint.
    */
-  def tags: List[String] = doc.tags
+  def tags: List[String] = documentation.tags
 
   /**
    * Transforms the input of this endpoint using the specified functions. This

zio-http/shared/src/main/scala/zio/http/endpoint/http/HttpGen.scala

@@ -47,7 +47,7 @@ object HttpGen {
   }
 
   private def doc(endpoint: Endpoint[_, _, _, _, _]) =
-    if (endpoint.doc == Doc.empty) None else Some(endpoint.doc.toPlaintext(color = false))
+    if (endpoint.documentation == Doc.empty) None else Some(endpoint.documentation.toPlaintext(color = false))
 
   def variables(inAtoms: AtomizedMetaCodecs): Seq[HttpVariable] =
     pathVariables(inAtoms) ++ queryVariables(inAtoms) ++ headersVariables(inAtoms) ++ bodyVariables(inAtoms)

zio-http/shared/src/main/scala/zio/http/endpoint/openapi/OpenAPI.scala

@@ -451,7 +451,7 @@ object OpenAPI {
 
     // todo maybe not the best regex, but the old one was not working at all
     // safe chars from RFC1738 "$" | "-" | "_" | "." | "+"
-    val validPath: Regex = """\/[\/a-zA-Z0-9\-_{}$.+]*""".r
+    private val validPath: Regex = """\/[\/a-zA-Z0-9\-_{}$.+]*""".r
 
     def fromString(name: String): Option[Path] = name match {
       case validPath() => Some(Path(name))

zio-http/shared/src/main/scala/zio/http/endpoint/openapi/OpenAPIGen.scala

@@ -515,7 +515,7 @@ object OpenAPIGen {
       val method0        = method(inAtoms.method)
       // Endpoint has only one doc. But open api has a summery and a description
       val pathItem       = OpenAPI.PathItem.empty
-        .copy(description = Some(endpoint.doc + endpoint.input.doc.getOrElse(Doc.empty)).filter(!_.isEmpty))
+        .copy(description = Some(endpoint.documentation + endpoint.input.doc.getOrElse(Doc.empty)).filter(!_.isEmpty))
       val pathItemWithOp = method0 match {
         case Method.OPTIONS => pathItem.addOptions(operation(endpoint))
         case Method.GET     => pathItem.addGet(operation(endpoint))
@@ -557,7 +557,7 @@ object OpenAPIGen {
     }
 
     def operation(endpoint: Endpoint[_, _, _, _, _]): OpenAPI.Operation = {
-      val maybeDoc = Some(endpoint.doc + pathDoc).filter(!_.isEmpty)
+      val maybeDoc = Some(endpoint.documentation + pathDoc).filter(!_.isEmpty)
       OpenAPI.Operation(
         tags = endpoint.tags,
         summary = None,