Update / document codecov.yml (javaparser#3418)

added documentation comments and ignores to `codecov.yml`

codecov.yml

@@ -3,45 +3,88 @@ codecov:
 
 
 coverage:
+
+  ## Configure decimal places, rounding, and the colour ranges used:
+  ## https://docs.codecov.com/docs/coverage-configuration
   precision: 3
   round: down
   range: "70...90" # Colour range - 70% coverage (and below) is solid red, 90% coverage (and above) is solid green.
 
-#  notify:
-#    gitter:
-#      default:
-#        url: "https://webhooks.gitter.im/e/683560e480138f1f8b1e"
-#        threshold: 1% # allow coverage to drop by 1% without posting a notification
-#        only_pulls: false
-#        branches:
-#          - "master"
-
-  # Split the coverage reporting into two sub-projects.
-  # https://docs.codecov.io/docs/commit-status
-  # https://docs.codecov.io/docs/codecovyml-reference#coveragestatus
+
+  ## These statuses show at the bottom of the PR.
+  ## Split the coverage reporting into sub-projects.
+  ## https://docs.codecov.io/docs/commit-status
+  ## https://docs.codecov.io/docs/codecovyml-reference#coveragestatus
   status:
+
+    ## Status configuration of the whole project
     project:
-      javaparser-core:
-        threshold: 0.5%
+
+      whole_project:             ## Whole project (note no flags specified)
+        target: auto             ## Increase overall coverage on each pull request (compared to the previous base commit)
+        threshold: 0.5%          ## Flexibility in allowing a minor drop in coverage
+
+      javaparser-core:           ## Just JavaParser Core
+        target: auto             ## Increase overall coverage on each pull request (compared to the previous base commit)
+        threshold: 0.5%          ## Flexibility in allowing a minor drop in coverage
+        ## TBC: Unclear if setting flags AND paths is redundant
         flags:
           - javaparser-core
         paths:
           - javaparser-core/src/main/java*
           - javaparser-core-testing/src/test/java*
           - javaparser-core-testing-bdd/src/test/java*
-      javaparser-symbol-solver:
-        threshold: 0.5%
+
+      javaparser-symbol-solver:  ## Just the Symbol Solver
+        target: auto             ## Increase overall coverage on each pull request (compared to the previous base commit)
+        threshold: 0.5%          ## Flexibility in allowing a minor drop in coverage
+        ## TBC: Unclear if setting flags AND paths is redundant
         flags:
           - javaparser-symbol-solver
         paths:
           - javaparser-symbol-solver-core/src/main/java*
           - javaparser-symbol-solver-testing/src/test/java*
 
-# Comments on PRs
+    ## Status configuration of ONLY the changed lines
+    patch:
+
+
+
+## Configuration of the comments that get added to PRs
 comment:
   layout: "reach,diff,flags,files,footer"
   behavior: default
   require_changes: false
   ### Do not comment on the PR until coverage reports for all builds has been received
   ### Note: 54 = three OSs (mac, windows, ubuntu) x nine java levels (8,9,10,11,12,13,14,15,16) x two modules (jp-core, jss)
   after_n_builds: 54
+
+
+## Flags defined elsewhere MUST also be defined here (required for GitHub PR checks information)
+flags:
+  javaparser-core:
+    paths:
+      - javaparser-core/src/main/java*
+      - javaparser-core-testing/src/test/java*
+      - javaparser-core-testing-bdd/src/test/java*
+    carryforward: false
+  javaparser-symbol-solver:
+    paths:
+    - javaparser-symbol-solver-core/src/main/java*
+    - javaparser-symbol-solver-testing/src/test/java*
+    carryforward: false
+
+
+# ## New section re: flags
+# ## No individual flags are added to YAML and flag names are automatically ingested from the Uploader
+# ## https://docs.codecov.com/docs/flags
+# flag_management:
+#   default_rules:
+#     carryforward: false
+
+
+ignore: 
+  - "/javaparser-core/src/main/java-templates/**"                     ## This source is ...
+# - "/javaparser-core/src/main/javacc-support/**"                     ## This source is generated by JavaCC
+  - "/javaparser-symbol-solver-testing/src/test/test_sourcecode/**"   ## This source is used as inputs to test cases
+