address review: drop superfluous comments, document overlaying domainpad

Remove the inline comments flagged in review, and describe in the
domainpad attribute that an overlaying axis uses the domainpad of the
axis it overlays. Regenerate the plot schema and the generated types.

Author: SharadhNaidu

src/components/fx/hover.js

@@ -2432,10 +2432,6 @@ function cleanPoint(d, hovermode) {
 /**
  * Get the pixel span of a spike with spikemode 'across'.
  *
- * The span covers the plot areas of all counter axes of `ax`. Each plot area is the
- * domain of the counter axis minus its `domainpad`. Thus the spike stops at the edge
- * of the plot area, and the padding stays clear for content such as a subplot title.
- *
  * @param gd - the graph div
  * @param ax - the full axis that shows the spike
  * @param gs - the plot size, `fullLayout._size`
@@ -2457,7 +2453,6 @@ function getAcrossSpikeSpan(gd, ax, gs) {
             start = Math.min(start, gs.l + counterAx.domain[0] * gs.w + padStart);
             end = Math.max(end, gs.l + counterAx.domain[1] * gs.w - padEnd);
         } else {
-            // SVG measures y from the top, so the top edge of the domain comes first
             start = Math.min(start, gs.t + (1 - counterAx.domain[1]) * gs.h + padStart);
             end = Math.max(end, gs.t + (1 - counterAx.domain[0]) * gs.h - padEnd);
         }

src/plots/cartesian/axes.js

@@ -4683,8 +4683,6 @@ function swapAxisGroup(gd, xIds, yIds) {
     var allAxKeys = Object.keys(axAttrs);
 
     var noSwapAttrs = [
-        // domainpad stays with domain: its keys name screen edges, so a swap of x and y
-        // would need to map left and right to top and bottom
         'anchor', 'domain', 'domainpad', 'overlaying', 'position', 'side',
         'tickangle', 'editType'
     ];

src/plots/cartesian/constraints.js

@@ -633,8 +633,6 @@ exports.clean = function clean(gd, ax) {
     }
 };
 
-// Get the `domainpad` of an axis as a fraction of the plot size.
-// The constraint solver works in domain fractions, not in pixels.
 function domainPadFraction(ax, fullLayout) {
     const pad = ax.domainpad;
     if(!pad) return 0;
@@ -650,11 +648,6 @@ function updateDomain(ax, factor, fullLayout) {
     var centerFraction = FROM_BL[ax.constraintoward];
     var center = inputDomain[0] + (inputDomain[1] - inputDomain[0]) * centerFraction;
 
-    // The constraint divides the drawn length of the axis by `factor`. Without padding,
-    // the drawn length is the domain span. `domainpad` removes a fixed number of pixels
-    // from the ends, so the drawn length is (span - padding), and only that part scales.
-    // Thus divide that part, then add the padding back. If the padding covers the full
-    // domain, nothing remains to scale, so divide the full span and let setScale clamp the padding.
     let divisor = factor;
     const padFraction = domainPadFraction(ax, fullLayout);
     if(padFraction > 0) {

src/plots/cartesian/layout_attributes.js

@@ -1202,7 +1202,9 @@ module.exports = {
             'so it can hold content with a fixed size, such as a subplot title.',
             'x axes use `left` and `right`. y axes use `top` and `bottom`.',
             'If the padding needs more room than the domain has, the two pads shrink by the same factor,',
-            'and the plot area keeps a length of at least 2 pixels.'
+            'and the plot area keeps a length of at least 2 pixels.',
+            'An axis that sets `overlaying` ignores its own `domainpad` and uses the `domainpad`',
+            'of the axis it overlays, so that both axes share the same plot area.'
         ].join(' ')
     },
     position: {

src/plots/cartesian/position_defaults.js

@@ -84,8 +84,6 @@ module.exports = function handlePositionDefaults(containerIn, containerOut, coer
         if(domain[0] > domain[1] - 1 / 4096) containerOut.domain = dfltDomain;
         Lib.noneOrAll(containerIn.domain, containerOut.domain, dfltDomain);
 
-        // Only the two sides along this axis have an effect. Do not coerce the other two,
-        // so that a value with no effect never gets into fullLayout.
         if(letter === 'x') {
             coerce('domainpad.left');
             coerce('domainpad.right');

src/plots/cartesian/set_convert.js

@@ -35,18 +35,11 @@ function isValidCategory(v) {
     return v !== null && v !== undefined;
 }
 
-// The smallest plot area in pixels that `domainpad` can leave. `doAutoMargin` keeps
-// the same floor for margins. A floor of 0 is not sufficient: setScale rejects only
-// negative lengths, so a length of 0 gives a slope of 0 and the subplot collapses with no error.
 const MIN_PADDED_LENGTH = 2;
 
 /**
  * Get the part of the requested `domainpad` that fits in a domain band.
  *
- * `domain` is a fraction of the plot area, so its band shrinks with the figure but the
- * padding does not. If the two pads need more room than the band has, the two pads
- * get the same scale factor. `doAutoMargin` uses the same method for margins.
- *
  * @param wanted - the total padding of the two edges, in pixels
  * @param bandLength - the length of the domain band, in pixels
  * @returns the factor from 0 to 1 to multiply each pad by
@@ -584,8 +577,6 @@ module.exports = function setConvert(ax, fullLayout) {
         if(ax.overlaying) {
             var ax2 = axisIds.getFromId({ _fullLayout: fullLayout }, ax.overlaying);
             ax.domain = ax2.domain;
-            // an overlaying axis has to sit on exactly the same plot area as the axis
-            // underneath it, so it takes that axis' padding along with its domain
             ax.domainpad = ax2.domainpad;
         }
 
@@ -604,8 +595,6 @@ module.exports = function setConvert(ax, fullLayout) {
         // the length in pixels of the domain band, before `domainpad`
         const bandLength = (isY ? gs.h : gs.w) * (ax.domain[1] - ax.domain[0]);
         const pad = ax.domainpad;
-        // _offset counts from the top for y and from the left for x,
-        // so padStart moves the plot area in from that edge
         let padStart = 0;
         let padEnd = 0;
 
@@ -619,9 +608,6 @@ module.exports = function setConvert(ax, fullLayout) {
         }
 
         ax._length = bandLength - padStart - padEnd;
-        // Keep the padding after the fit. scattergl, splom and hover spikes add these
-        // values to their `domain` math. A rebuild from _offset and _length would change
-        // the last bits of the result, also for an axis with no padding.
         ax._padStart = padStart;
         ax._padEnd = padEnd;
 

src/traces/scattergl/plot.js

@@ -29,9 +29,6 @@ function getViewport(fullLayout, xaxis, yaxis, plotGlPixelRatio) {
     var w = gs.w * plotGlPixelRatio;
     var h = gs.h * plotGlPixelRatio;
 
-    // `domain` does not include `domainpad`, so add the padding to the rect here.
-    // A rebuild from _offset and _length would move the rect by a fraction of a pixel,
-    // also for an axis with no padding.
     const padL = (xaxis._padStart || 0) * plotGlPixelRatio;
     const padR = (xaxis._padEnd || 0) * plotGlPixelRatio;
     const padT = (yaxis._padStart || 0) * plotGlPixelRatio;

src/traces/splom/base_plot.js

@@ -137,8 +137,6 @@ function makeGridData(gd) {
 
         // ya.l2p assumes top-to-bottom coordinate system (a la SVG),
         // we need to compute bottom-to-top offsets and slopes:
-        // add the bottom `domainpad` to the domain math, because a read of _offset
-        // would move an axis with no padding by a fraction of a pixel
         const yOffset = gs.b + ya.domain[0] * gs.h + (ya._padEnd || 0);
         var ym = -ya._m;
         var yb = -ym * ya.r2l(ya.range[0], ya.calendar);

src/traces/splom/plot.js

@@ -41,10 +41,6 @@ function plotOne(gd, cd0) {
     viewOpts.ranges = new Array(visibleLength);
     viewOpts.domains = new Array(visibleLength);
 
-    // regl-splom places each cell as a fraction of the full plot area. Convert `domainpad`
-    // to the same fractions, or the cells keep their size while the axes move. Add the
-    // padding to `domain` here, because a rebuild from _offset and _length moves every
-    // cell a little, also for an axis with no padding.
     const padFrac = (px, total) => (px || 0) / total;
 
     for(k = 0; k < visibleDims.length; k++) {

src/types/generated/schema.d.ts

@@ -12199,7 +12199,7 @@ export interface LayoutAxis {
      * @default [0,1]
      */
     domain?: [number, number];
-    /** Sets the space in pixels to reserve inside the edges of `domain`. Because `domain` is a fraction of the plot area, the gap between subplots changes with the figure size. `domainpad` keeps the same size in pixels at all figure sizes, so it can hold content with a fixed size, such as a subplot title. x axes use `left` and `right`. y axes use `top` and `bottom`. If the padding needs more room than the domain has, the two pads shrink by the same factor, and the plot area keeps a length of at least 2 pixels. */
+    /** Sets the space in pixels to reserve inside the edges of `domain`. Because `domain` is a fraction of the plot area, the gap between subplots changes with the figure size. `domainpad` keeps the same size in pixels at all figure sizes, so it can hold content with a fixed size, such as a subplot title. x axes use `left` and `right`. y axes use `top` and `bottom`. If the padding needs more room than the domain has, the two pads shrink by the same factor, and the plot area keeps a length of at least 2 pixels. An axis that sets `overlaying` ignores its own `domainpad` and uses the `domainpad` of the axis it overlays, so that both axes share the same plot area. */
     domainpad?: {
         /**
          * Sets the space in pixels to reserve inside the bottom edge of `domain`. Applies to y axes only.