From 586542d98e95674d8b3ef92f5e9be35686af4863 Mon Sep 17 00:00:00 2001
From: Cody Allen <ceedubs@gmail.com>
Date: Thu, 7 Dec 2017 14:52:54 -0800
Subject: [PATCH] Add grouping to scaladoc for arity methods

This makes it so when you look at the `Applicative` scaladoc you don't
have a bunch of `ap3`, `ap4`, etc noise mixed in with the more
meaningful methods. Instead, the generated higher-arity methods show up
in separate scaladoc groups below.

To see the changes you can pull this branch, run `sbt unidoc` (you may
need to clean first), and open
`cats/docs/target/scala-2.12/unidoc/cats/Applicative.html` in your
browser.
---
 build.sbt                 |  1 +
 project/Boilerplate.scala | 57 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/build.sbt b/build.sbt
index c0768dc1f51..85a56df5e23 100644
--- a/build.sbt
+++ b/build.sbt
@@ -178,6 +178,7 @@ lazy val docSettings = Seq(
   fork in (ScalaUnidoc, unidoc) := true,
   scalacOptions in (ScalaUnidoc, unidoc) ++= Seq(
     "-Xfatal-warnings",
+    "-groups",
     "-doc-source-url", scmInfo.value.get.browseUrl + "/tree/master€{FILE_PATH}.scala",
     "-sourcepath", baseDirectory.in(LocalRootProject).value.getAbsolutePath,
     "-diagrams"
diff --git a/project/Boilerplate.scala b/project/Boilerplate.scala
index 2f132681220..06185201d3c 100644
--- a/project/Boilerplate.scala
+++ b/project/Boilerplate.scala
@@ -184,10 +184,29 @@ object Boilerplate {
 
       block"""
         |package cats
+        |
+        |/**
+        | * @groupprio Ungrouped 0
+        | *
+        | * @groupname ApArity ap arity
+        | * @groupdesc ApArity Higher-arity ap methods
+        | * @groupprio ApArity 999
+        | *
+        | * @groupname MapArity map arity
+        | * @groupdesc MapArity Higher-arity map methods
+        | * @groupprio MapArity 999
+        | *
+        | * @groupname TupleArity tuple arity
+        | * @groupdesc TupleArity Higher-arity tuple methods
+        | * @groupprio TupleArity 999
+        | */
         |trait ApplyArityFunctions[F[_]] { self: Apply[F] =>
         |  def tuple2[A, B](f1: F[A], f2: F[B]): F[(A, B)] = Semigroupal.tuple2(f1, f2)(self, self)
+        -  /** @group ApArity */
         -  def ap$arity[${`A..N`}, Z](f: F[(${`A..N`}) => Z])($fparams):F[Z] = $apply
+        -  /** @group MapArity */
         -  def map$arity[${`A..N`}, Z]($fparams)(f: (${`A..N`}) => Z): F[Z] = Semigroupal.map$arity($fparams)(f)(self, self)
+        -  /** @group TupleArity */
         -  def tuple$arity[${`A..N`}, Z]($fparams): F[(${`A..N`})] = Semigroupal.tuple$arity($fparams)(self, self)
         |}
       """
@@ -210,7 +229,16 @@ object Boilerplate {
 
       block"""
          |package cats
+         |
+         |/**
+         | * @groupprio Ungrouped 0
+         | *
+         | * @groupname ParMapArity parMap arity
+         | * @groupdesc ParMapArity Higher-arity parMap methods
+         | * @groupprio ParMapArity 999
+         | */
          |trait ParallelArityFunctions {
+        -  /** @group parmaparity */
         -  def parMap$arity[M[_], F[_], ${`A..N`}, Z]($fparams)(f: (${`A..N`}) => Z)(implicit p: NonEmptyParallel[M, F]): M[Z] =
         -    p.flatMap.map($nestedProducts) { case ${`nested (a..n)`} => f(${`a..n`}) }
          |}
@@ -234,15 +262,44 @@ object Boilerplate {
 
       block"""
          |package cats
+         |
+         |/**
+         | * @groupprio Ungrouped 0
+         | *
+         | * @groupname MapArity map arity
+         | * @groupdesc MapArity Higher-arity map methods
+         | * @groupprio MapArity 999
+         | *
+         | * @groupname ContramapArity contramap arity
+         | * @groupdesc ContramapArity Higher-arity contramap methods
+         | * @groupprio ContramapArity 999
+         | *
+         | * @groupname ImapArity imap arity
+         | * @groupdesc ImapArity Higher-arity imap methods
+         | * @groupprio ImapArity 999
+         | *
+         | * @groupname TupleArity tuple arity
+         | * @groupdesc TupleArity Higher-arity tuple methods
+         | * @groupprio TupleArity 999
+         | *
+         | * @groupname TraverseArity traverse arity
+         | * @groupdesc TraverseArity Higher-arity traverse methods
+         | * @groupprio TraverseArity 999
+         | */
          |trait SemigroupalArityFunctions {
+        -  /** @group MapArity */
         -  def map$arity[F[_], ${`A..N`}, Z]($fparams)(f: (${`A..N`}) => Z)(implicit semigroupal: Semigroupal[F], functor: Functor[F]): F[Z] =
         -    functor.map($nestedProducts) { case ${`nested (a..n)`} => f(${`a..n`}) }
+        -  /** @group ContramapArity */
         -  def contramap$arity[F[_], ${`A..N`}, Z]($fparams)(f: Z => (${`A..N`}))(implicit semigroupal: Semigroupal[F], contravariant: Contravariant[F]):F[Z] =
         -    contravariant.contramap($nestedProducts) { z => val ${`(a..n)`} = f(z); ${`nested (a..n)`} }
+        -  /** @group ImapArity */
         -  def imap$arity[F[_], ${`A..N`}, Z]($fparams)(f: (${`A..N`}) => Z)(g: Z => (${`A..N`}))(implicit semigroupal: Semigroupal[F], invariant: Invariant[F]):F[Z] =
         -    invariant.imap($nestedProducts) { case ${`nested (a..n)`} => f(${`a..n`}) } { z => val ${`(a..n)`} = g(z); ${`nested (a..n)`} }
+        -  /** @group TupleArity */
         -  def tuple$arity[F[_], ${`A..N`}]($fparams)(implicit semigroupal: Semigroupal[F], invariant: Invariant[F]):F[(${`A..N`})] =
         -    imap$arity($fargsS)((${`_.._`}))(identity)
+        -  /** @group TraverseArity */
         -  def traverse$arity[F[_], G[_], ${`A..N`}, Z]($fparams)(f: (${`A..N`}) => G[Z])(implicit semigroupal: Semigroupal[F], traverse: Traverse[F], applicative: Applicative[G]): G[F[Z]] =
         -    traverse.traverse($nestedProducts) { case ${`nested (a..n)`} => f(${`a..n`}) }
          |}