diff --git a/Cabal/src/Distribution/PackageDescription/Check.hs b/Cabal/src/Distribution/PackageDescription/Check.hs
index a0c796766e2..1021bc530e8 100644
--- a/Cabal/src/Distribution/PackageDescription/Check.hs
+++ b/Cabal/src/Distribution/PackageDescription/Check.hs
@@ -196,7 +196,7 @@ checkGenericPackageDescription
       condLibrary_ condSubLibraries_ condForeignLibs_ condExecutables_
       condTestSuites_ condBenchmarks_)
     = do
-        -- * Description and names.
+        -- § Description and names.
         checkPackageDescription packageDescription_
           -- Targets should be present...
         let condAllLibraries = maybeToList condLibrary_ ++
@@ -219,13 +219,13 @@ checkGenericPackageDescription
           -- Flag names.
         mapM_ checkFlagName genPackageFlags_
 
-        -- * Feature checks.
+        -- § Feature checks.
         checkSpecVer CabalSpecV2_0 (not . null $ condSubLibraries_)
           (PackageDistInexcusable CVMultiLib)
         checkSpecVer CabalSpecV1_8 (not . null $ condTestSuites_)
           (PackageDistInexcusable CVTestSuite)
 
-        -- * Conditional targets
+        -- § Conditional targets
         case condLibrary_ of
           Just cl -> checkCondTarget
                         genPackageFlags_
@@ -295,7 +295,7 @@ checkPackageDescription
       _subLibraries_ _executables_ _foreignLibs_ _testSuites_ _benchmarks_
       dataFiles_ dataDir_ extraSrcFiles_ extraTmpFiles_ extraDocFiles_) = do
 
-        -- * Sanity checks.
+        -- § Sanity checks.
         checkPackageId package_
         -- TODO `name` is caught at parse level, remove this test.
         let pn = packageName package_
@@ -309,7 +309,7 @@ checkPackageDescription
         checkP (any (== prettyShow pn) (prettyShow <$> nsubs))
           (PackageBuildImpossible $ IllegalLibraryName pn)
 
-        -- * Fields check.
+        -- § Fields check.
         checkNull category_
           (PackageDistSuspicious $ MissingField CEFCategory)
         checkNull maintainer_
@@ -326,7 +326,7 @@ checkPackageDescription
                  ShortText.length description_ <= ShortText.length synopsis_)
           (PackageDistSuspicious ShortDesc)
 
-        -- * Paths.
+        -- § Paths.
         mapM_ (checkPath False "extra-source-files" PathKindGlob) extraSrcFiles_
         mapM_ (checkPath False "extra-tmp-files" PathKindFile) extraTmpFiles_
         mapM_ (checkPath False "extra-doc-files" PathKindGlob) extraDocFiles_
@@ -340,7 +340,7 @@ checkPackageDescription
         mapM_ (checkGlob "extra-source-files") extraSrcFiles_
         mapM_ (checkGlob "extra-doc-files") extraDocFiles_
 
-        -- * Datafield checks.
+        -- § Datafield checks.
         checkSetupBuildInfo setupBuildInfo_
         mapM_ checkTestedWith testedWith_
         either checkNewLicense
@@ -567,7 +567,7 @@ checkLibrary isSub lib@(Library
                                     (view L.autogenIncludes lib)) $
           (PackageBuildImpossible AutogenIncludesNotIncluded)
 
-        -- * Build infos.
+        -- § Build infos.
         checkBuildInfo BITLib (explicitLibModules lib) libBuildInfo_
 
         -- Feature checks.
@@ -591,7 +591,7 @@ checkForeignLib (ForeignLib
 checkExecutable :: Monad m => PackageId -> Executable -> CheckM m ()
 checkExecutable pid exe@(Executable
                            exeName_ modulePath_ _exeScope_ buildInfo_) = do
-        -- * Exe specific checks
+        -- § Exe specific checks
         checkP (null modulePath_)
           (PackageBuildImpossible (NoMainIs exeName_))
           -- This check does not apply to scripts.
@@ -600,7 +600,7 @@ checkExecutable pid exe@(Executable
                not (fileExtensionSupportedLanguage $ modulePath_))
           (PackageBuildImpossible NoHsLhsMain)
 
-        -- * Features check
+        -- § Features check
         checkSpecVer CabalSpecV1_18
           (fileExtensionSupportedLanguage modulePath_ &&
            takeExtension modulePath_ `notElem` [".hs", ".lhs"])
@@ -614,14 +614,14 @@ checkExecutable pid exe@(Executable
                                     (view L.autogenIncludes exe))
           (PackageBuildImpossible AutogenIncludesNotIncludedExe)
 
-        -- * Build info checks.
+        -- § Build info checks.
         checkBuildInfo BITOther [] buildInfo_
 
 checkTestSuite :: Monad m => TestSuite -> CheckM m ()
 checkTestSuite ts@(TestSuite
                      testName_ testInterface_ testBuildInfo_
                      _testCodeGenerators_) = do
-        -- * TS specific checks.
+        -- § TS specific checks.
         -- TODO caught by the parser, can remove safely
         case testInterface_ of
           TestSuiteUnsupported tt@(TestTypeUnknown _ _) ->
@@ -638,12 +638,12 @@ checkTestSuite ts@(TestSuite
                          (view L.autogenIncludes ts))
           (PackageBuildImpossible AutogenIncludesNotIncludedExe)
 
-        -- * Feature checks.
+        -- § Feature checks.
         checkSpecVer CabalSpecV1_18
           (mainIsNotHsExt && not mainIsWrongExt)
           (PackageDistInexcusable MainCCabal1_18)
 
-        -- * Build info checks.
+        -- § Build info checks.
         checkBuildInfo BITTestBench [] testBuildInfo_
   where
         mainIsWrongExt =
@@ -660,7 +660,7 @@ checkBenchmark :: Monad m => Benchmark -> CheckM m ()
 checkBenchmark bm@(Benchmark
                      benchmarkName_ benchmarkInterface_
                      benchmarkBuildInfo_) = do
-        -- * Interface & bm specific tests.
+        -- § Interface & bm specific tests.
         case benchmarkInterface_ of
           BenchmarkUnsupported tt@(BenchmarkTypeUnknown _ _) ->
             tellP (PackageBuildWarning $ BenchmarkTypeNotKnown tt)
@@ -678,7 +678,7 @@ checkBenchmark bm@(Benchmark
                          (view L.autogenIncludes bm))
           (PackageBuildImpossible AutogenIncludesNotIncludedExe)
 
-        -- * BuildInfo checks.
+        -- § BuildInfo checks.
         checkBuildInfo BITTestBench [] benchmarkBuildInfo_
     where
           -- Cannot abstract with similar function in checkTestSuite,
@@ -708,7 +708,7 @@ data BITarget = BITLib | BITTestBench | BITOther
 checkBuildInfo :: Monad m => BITarget -> [ModuleName] -> BuildInfo ->
                   CheckM m ()
 checkBuildInfo t ams bi = do
-        -- * Options.
+        -- § Options.
         checkGHCOptions "ghc-options" t (hcOptions GHC bi)
         checkGHCOptions "ghc-prof-options" t (hcProfOptions GHC bi)
         checkGHCOptions "ghc-shared-options" t (hcSharedOptions GHC bi)
@@ -717,7 +717,7 @@ checkBuildInfo t ams bi = do
         checkCLikeOptions "C++" "cxx-options" (cxxOptions bi) ldOpts
         checkCPPOptions (cppOptions bi)
 
-        -- * Paths: content.
+        -- § Paths: content.
         mapM_ checkLang (allLanguages bi)
         mapM_ checkExt (allExtensions bi)
         mapM_ checkDep (targetBuildDepends bi)
@@ -726,7 +726,7 @@ checkBuildInfo t ams bi = do
         let ds = buildToolDepends bi ++ catMaybes (map df $ buildTools bi)
         mapM_ checkBTDep ds
 
-        -- * Paths: well formedness
+        -- § Paths: well formedness
         mapM_ (checkPath False "asm-sources" PathKindFile) (asmSources bi)
         mapM_ (checkPath False "cmm-sources" PathKindFile) (cmmSources bi)
         mapM_ (checkPath False "c-sources" PathKindFile) (cSources bi)
@@ -746,7 +746,7 @@ checkBuildInfo t ams bi = do
             (extraLibDirsStatic bi)
         mapM_ checkOptionPath (perCompilerFlavorToList $ options bi)
 
-        -- * Feature checks --
+        -- § Feature checks --
         sv <- asksCM ccSpecVersion
         checkSpecVer CabalSpecV1_10 (isJust $ defaultLanguage bi)
           (PackageBuildWarning CVDefaultLanguage)