revise docs in histogram

jcupitt · jcupitt · commit 4a56261f44d8 · 2025-04-27T12:39:38.000+01:00
diff --git a/doc/rename.sed b/doc/rename.sed
@@ -396,6 +396,7 @@ s/vips_\(stats\)()/[method@Image.\1]/g
 s/vips_\(stdif\)()/[method@Image.\1]/g
 s/vips_\(subsample\)()/[method@Image.\1]/g
 s/vips_\(subtract\)()/[method@Image.\1]/g
+s/vips_\(switch\)()/[func@Image.\1]/g
 s/vips_\(tanh\)()/[method@Image.\1]/g
 s/vips_\(tan\)()/[method@Image.\1]/g
 s/vips_\(text\)()/[ctor@Image.\1]/g
diff --git a/libvips/histogram/case.c b/libvips/histogram/case.c
@@ -290,10 +290,11 @@ vips_casev(VipsImage *index, VipsImage **cases, VipsImage **out, int n,
  * The output image is the same size as @index. Images in @cases are
  * expanded to the smallest common format and number of bands.
  *
- * Combine this with vips_switch() to make something like a case statement or
- * a multi-way vips_ifthenelse().
+ * Combine this with [method@Image.switch] to make something like a case statement or
+ * a multi-way [method@Image.ifthenelse].
  *
- * See also: vips_maplut(), vips_switch(), vips_ifthenelse().
+ * ::: seealso
+ *     [method@Image.maplut], [method@Image.switch], [method@Image.ifthenelse].
  *
  * Returns: 0 on success, -1 on error
  */
diff --git a/libvips/histogram/hist_cum.c b/libvips/histogram/hist_cum.c
@@ -174,7 +174,8 @@ vips_hist_cum_init(VipsHistCum *hist_cum)
  *
  * Form cumulative histogram.
  *
- * See also: vips_hist_norm().
+ * ::: seealso
+ *     [method@Image.hist_norm].
  *
  * Returns: 0 on success, -1 on error
  */
diff --git a/libvips/histogram/hist_equal.c b/libvips/histogram/hist_equal.c
@@ -142,15 +142,14 @@ vips_hist_equal_init(VipsHistEqual *equal)
  * @out: (out): output image
  * @...: %NULL-terminated list of optional named arguments
  *
- * Optional arguments:
+ * Histogram-equalise @in.
  *
- * * @band: band to equalise
- *
- * Histogram-equalise @in. Equalise using band @bandno, or if @bandno is -1,
+ * Equalise using band @bandno, or if @bandno is -1,
  * equalise bands independently. The output format is always the same as the
  * input format.
  *
- * See also:
+ * ::: tip "Optional arguments"
+ *     * @band: %gint, band to equalise
  *
  * Returns: 0 on success, -1 on error
  */
diff --git a/libvips/histogram/hist_local.c b/libvips/histogram/hist_local.c
@@ -404,10 +404,6 @@ vips_hist_local_init(VipsHistLocal *local)
  * @height: height of region
  * @...: %NULL-terminated list of optional named arguments
  *
- * Optional arguments:
- *
- * * @max_slope: maximum brightening
- *
  * Performs local histogram equalisation on @in using a
  * window of size @width by @height centered on the input pixel.
  *
@@ -419,7 +415,11 @@ vips_hist_local_init(VipsHistLocal *local)
  * performed. A value of 3 is often used. Local histogram equalization with
  * contrast limiting is usually called CLAHE.
  *
- * See also: vips_hist_equal().
+ * ::: tip "Optional arguments"
+ *     * @max_slope: %gint, maximum brightening
+ *
+ * ::: seealso
+ *     [method@Image.hist_equal].
  *
  * Returns: 0 on success, -1 on error
  */
diff --git a/libvips/histogram/hist_match.c b/libvips/histogram/hist_match.c
@@ -186,8 +186,9 @@ vips_hist_match_init(VipsHistMatch *match)
  * cumulative histograms, @out will be a LUT that adjusts the PDF of the image
  * from which @in was made to match the PDF of @ref's image.
  *
- * See also: vips_maplut(), vips_hist_find(), vips_hist_norm(),
- * vips_hist_cum().
+ * ::: seealso
+ *     [method@Image.maplut], [method@Image.hist_find], [method@Image.hist_norm],
+ * [method@Image.hist_cum].
  *
  * Returns: 0 on success, -1 on error
  */
diff --git a/libvips/histogram/hist_norm.c b/libvips/histogram/hist_norm.c
@@ -165,7 +165,8 @@ vips_hist_norm_init(VipsHistNorm *hist_norm)
  * index, so for example the max for a uchar image becomes 255.
  * Normalise each band separately.
  *
- * See also: vips_hist_cum().
+ * ::: seealso
+ *     [method@Image.hist_cum].
  *
  * Returns: 0 on success, -1 on error
  */
diff --git a/libvips/histogram/maplut.c b/libvips/histogram/maplut.c
@@ -779,10 +779,6 @@ vips_maplut_init(VipsMaplut *maplut)
  * @lut: look-up table
  * @...: %NULL-terminated list of optional named arguments
  *
- * Optional arguments:
- *
- * * @band: apply one-band @lut to this band of @in
- *
  * Map an image through another image acting as a LUT (Look Up Table).
  * The lut may have any type and the output image will be that type.
  *
@@ -804,7 +800,11 @@ vips_maplut_init(VipsMaplut *maplut)
  * separately. If @in has one band, then @lut may have many bands and
  * the output will have the same number of bands as @lut.
  *
- * See also: vips_hist_find(), vips_identity().
+ * ::: tip "Optional arguments"
+ *     * @band: %gint, apply one-band @lut to this band of @in
+ *
+ * ::: seealso
+ *     [method@Image.hist_find], [ctor@Image.identity].
  *
  * Returns: 0 on success, -1 on error
  */
diff --git a/libvips/histogram/percent.c b/libvips/histogram/percent.c
@@ -138,7 +138,7 @@ vips_percent_init(VipsPercent *percent)
  * @threshold: (out): output threshold value
  * @...: %NULL-terminated list of optional named arguments
  *
- * vips_percent() returns (through the @threshold parameter) the threshold
+ * [method@Image.percent] returns (through the @threshold parameter) the threshold
  * below which there are @percent values of @in. For example:
  *
  * |[
@@ -151,7 +151,8 @@ vips_percent_init(VipsPercent *percent)
  * The function works for uchar and ushort images only.  It can be used
  * to threshold the scaled result of a filtering operation.
  *
- * See also: vips_hist_find(), vips_profile().
+ * ::: seealso
+ *     [method@Image.hist_find], [method@Image.profile].
  *
  * Returns: 0 on success, -1 on error
  */
diff --git a/libvips/histogram/stdif.c b/libvips/histogram/stdif.c
@@ -366,25 +366,20 @@ vips_stdif_init(VipsStdif *stdif)
  * @height: height of region
  * @...: %NULL-terminated list of optional named arguments
  *
- * Optional arguments:
+ * [method@Image.stdif] performs statistical differencing according to the
+ * formula given in page 45 of the book "An Introduction to Digital Image
+ * Processing" by Wayne Niblack.
  *
- * * @a: weight of new mean
- * * @m0: target mean
- * * @b: weight of new deviation
- * * @s0: target deviation
- *
- * vips_stdif() performs statistical differencing according to the formula
- * given in page 45 of the book "An Introduction to Digital Image
- * Processing" by Wayne Niblack. This transformation emphasises the way in
+ * This transformation emphasises the way in
  * which a pel differs statistically from its neighbours. It is useful for
  * enhancing low-contrast images with lots of detail, such as X-ray plates.
  *
  * At point (i,j) the output is given by the equation:
  *
- * |[
+ * ```
  * vout(i,j) = @a * @m0 + (1 - @a) * meanv +
  *       (vin(i,j) - meanv) * (@b * @s0) / (@s0 + @b * stdv)
- * ]|
+ * ```
  *
  * Values @a, @m0, @b and @s0 are entered, while meanv and stdv are the values
  * calculated over a moving window of size @width, @height centred on pixel
@@ -393,15 +388,22 @@ vips_stdif_init(VipsStdif *stdif)
  *
  * Try:
  *
- * |[
+ * ```
  * vips stdif $VIPSHOME/pics/huysum.v fred.v 0.5 128 0.5 50 11 11
- * ]|
+ * ```
  *
  * The operation works on one-band uchar images only, and writes a one-band
  * uchar image as its result. The output image has the same size as the
  * input.
  *
- * See also: vips_hist_local().
+ * ::: tip "Optional arguments"
+ *     * @a: %gdouble, weight of new mean
+ *     * @m0: %gdouble, target mean
+ *     * @b: %gdouble, weight of new deviation
+ *     * @s0: %gdouble, target deviation
+ *
+ * ::: seealso
+ *     [method@Image.hist_local].
  *
  * Returns: 0 on success, -1 on error
  */

Original file line number	Diff line number	Diff line change
`@@ -290,10 +290,11 @@ vips_casev(VipsImage index, VipsImage cases, VipsImage *out, int n,`
`290`	`290`	`* The output image is the same size as @index. Images in @cases are`
`291`	`291`	`* expanded to the smallest common format and number of bands.`
`292`	`292`	`*`
`293`		`- * Combine this with vips_switch() to make something like a case statement or`
`294`		`- * a multi-way vips_ifthenelse().`
	`293`	`+ * Combine this with [method@Image.switch] to make something like a case statement or`
	`294`	`+ * a multi-way [method@Image.ifthenelse].`
`295`	`295`	`*`
`296`		`- * See also: vips_maplut(), vips_switch(), vips_ifthenelse().`
	`296`	`+ * ::: seealso`
	`297`	`+ * [method@Image.maplut], [method@Image.switch], [method@Image.ifthenelse].`
`297`	`298`	`*`
`298`	`299`	`* Returns: 0 on success, -1 on error`
`299`	`300`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -174,7 +174,8 @@ vips_hist_cum_init(VipsHistCum *hist_cum)`
`174`	`174`	`*`
`175`	`175`	`* Form cumulative histogram.`
`176`	`176`	`*`
`177`		`- * See also: vips_hist_norm().`
	`177`	`+ * ::: seealso`
	`178`	`+ * [method@Image.hist_norm].`
`178`	`179`	`*`
`179`	`180`	`* Returns: 0 on success, -1 on error`
`180`	`181`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -142,15 +142,14 @@ vips_hist_equal_init(VipsHistEqual *equal)`
`142`	`142`	`* @out: (out): output image`
`143`	`143`	`* @...: %NULL-terminated list of optional named arguments`
`144`	`144`	`*`
`145`		`- * Optional arguments:`
	`145`	`+ * Histogram-equalise @in.`
`146`	`146`	`*`
`147`		`- * * @band: band to equalise`
`148`		`- *`
`149`		`- * Histogram-equalise @in. Equalise using band @bandno, or if @bandno is -1,`
	`147`	`+ * Equalise using band @bandno, or if @bandno is -1,`
`150`	`148`	`* equalise bands independently. The output format is always the same as the`
`151`	`149`	`* input format.`
`152`	`150`	`*`
`153`		`- * See also:`
	`151`	`+ * ::: tip "Optional arguments"`
	`152`	`+ * * @band: %gint, band to equalise`
`154`	`153`	`*`
`155`	`154`	`* Returns: 0 on success, -1 on error`
`156`	`155`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -404,10 +404,6 @@ vips_hist_local_init(VipsHistLocal *local)`
`404`	`404`	`* @height: height of region`
`405`	`405`	`* @...: %NULL-terminated list of optional named arguments`
`406`	`406`	`*`
`407`		`- * Optional arguments:`
`408`		`- *`
`409`		`- * * @max_slope: maximum brightening`
`410`		`- *`
`411`	`407`	`* Performs local histogram equalisation on @in using a`
`412`	`408`	`* window of size @width by @height centered on the input pixel.`
`413`	`409`	`*`
`@@ -419,7 +415,11 @@ vips_hist_local_init(VipsHistLocal *local)`
`419`	`415`	`* performed. A value of 3 is often used. Local histogram equalization with`
`420`	`416`	`* contrast limiting is usually called CLAHE.`
`421`	`417`	`*`
`422`		`- * See also: vips_hist_equal().`
	`418`	`+ * ::: tip "Optional arguments"`
	`419`	`+ * * @max_slope: %gint, maximum brightening`
	`420`	`+ *`
	`421`	`+ * ::: seealso`
	`422`	`+ * [method@Image.hist_equal].`
`423`	`423`	`*`
`424`	`424`	`* Returns: 0 on success, -1 on error`
`425`	`425`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -186,8 +186,9 @@ vips_hist_match_init(VipsHistMatch *match)`
`186`	`186`	`* cumulative histograms, @out will be a LUT that adjusts the PDF of the image`
`187`	`187`	`* from which @in was made to match the PDF of @ref's image.`
`188`	`188`	`*`
`189`		`- * See also: vips_maplut(), vips_hist_find(), vips_hist_norm(),`
`190`		`- * vips_hist_cum().`
	`189`	`+ * ::: seealso`
	`190`	`+ * [method@Image.maplut], [method@Image.hist_find], [method@Image.hist_norm],`
	`191`	`+ * [method@Image.hist_cum].`
`191`	`192`	`*`
`192`	`193`	`* Returns: 0 on success, -1 on error`
`193`	`194`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -165,7 +165,8 @@ vips_hist_norm_init(VipsHistNorm *hist_norm)`
`165`	`165`	`* index, so for example the max for a uchar image becomes 255.`
`166`	`166`	`* Normalise each band separately.`
`167`	`167`	`*`
`168`		`- * See also: vips_hist_cum().`
	`168`	`+ * ::: seealso`
	`169`	`+ * [method@Image.hist_cum].`
`169`	`170`	`*`
`170`	`171`	`* Returns: 0 on success, -1 on error`
`171`	`172`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -779,10 +779,6 @@ vips_maplut_init(VipsMaplut *maplut)`
`779`	`779`	`* @lut: look-up table`
`780`	`780`	`* @...: %NULL-terminated list of optional named arguments`
`781`	`781`	`*`
`782`		`- * Optional arguments:`
`783`		`- *`
`784`		`- * * @band: apply one-band @lut to this band of @in`
`785`		`- *`
`786`	`782`	`* Map an image through another image acting as a LUT (Look Up Table).`
`787`	`783`	`* The lut may have any type and the output image will be that type.`
`788`	`784`	`*`
`@@ -804,7 +800,11 @@ vips_maplut_init(VipsMaplut *maplut)`
`804`	`800`	`* separately. If @in has one band, then @lut may have many bands and`
`805`	`801`	`* the output will have the same number of bands as @lut.`
`806`	`802`	`*`
`807`		`- * See also: vips_hist_find(), vips_identity().`
	`803`	`+ * ::: tip "Optional arguments"`
	`804`	`+ * * @band: %gint, apply one-band @lut to this band of @in`
	`805`	`+ *`
	`806`	`+ * ::: seealso`
	`807`	`+ * [method@Image.hist_find], [ctor@Image.identity].`
`808`	`808`	`*`
`809`	`809`	`* Returns: 0 on success, -1 on error`
`810`	`810`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -138,7 +138,7 @@ vips_percent_init(VipsPercent *percent)`
`138`	`138`	`* @threshold: (out): output threshold value`
`139`	`139`	`* @...: %NULL-terminated list of optional named arguments`
`140`	`140`	`*`
`141`		`- * vips_percent() returns (through the @threshold parameter) the threshold`
	`141`	`+ * [method@Image.percent] returns (through the @threshold parameter) the threshold`
`142`	`142`	`* below which there are @percent values of @in. For example:`
`143`	`143`	`*`
`144`	`144`	`* \|[`
`@@ -151,7 +151,8 @@ vips_percent_init(VipsPercent *percent)`
`151`	`151`	`* The function works for uchar and ushort images only. It can be used`
`152`	`152`	`* to threshold the scaled result of a filtering operation.`
`153`	`153`	`*`
`154`		`- * See also: vips_hist_find(), vips_profile().`
	`154`	`+ * ::: seealso`
	`155`	`+ * [method@Image.hist_find], [method@Image.profile].`
`155`	`156`	`*`
`156`	`157`	`* Returns: 0 on success, -1 on error`
`157`	`158`	`*/`