Remove redundant doc comments on standard arguments (#5725)

crates/typst-library/src/foundations/args.rs

@@ -305,8 +305,6 @@ impl Args {
     /// ```
     #[func(constructor)]
     pub fn construct(
-        /// The real arguments (the other argument is just for the docs).
-        /// The docs argument cannot be called `args`.
         args: &mut Args,
         /// The arguments to construct.
         #[external]

crates/typst-library/src/foundations/array.rs

@@ -301,9 +301,7 @@ impl Array {
     #[func]
     pub fn find(
         &self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
         /// The function to apply to each item. Must return a boolean.
         searcher: Func,
@@ -325,9 +323,7 @@ impl Array {
     #[func]
     pub fn position(
         &self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
         /// The function to apply to each item. Must return a boolean.
         searcher: Func,
@@ -363,8 +359,6 @@ impl Array {
     /// ```
     #[func]
     pub fn range(
-        /// The real arguments (the other arguments are just for the docs, this
-        /// function is a bit involved, so we parse the arguments manually).
         args: &mut Args,
         /// The start of the range (inclusive).
         #[external]
@@ -402,9 +396,7 @@ impl Array {
     #[func]
     pub fn filter(
         &self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
         /// The function to apply to each item. Must return a boolean.
         test: Func,
@@ -427,9 +419,7 @@ impl Array {
     #[func]
     pub fn map(
         self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
         /// The function to apply to each item.
         mapper: Func,
@@ -481,8 +471,6 @@ impl Array {
     #[func]
     pub fn zip(
         self,
-        /// The real arguments (the `others` arguments are just for the docs, this
-        /// function is a bit involved, so we parse the positional arguments manually).
         args: &mut Args,
         /// Whether all arrays have to have the same length.
         /// For example, `{(1, 2).zip((1, 2, 3), exact: true)}` produces an
@@ -569,9 +557,7 @@ impl Array {
     #[func]
     pub fn fold(
         self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
         /// The initial value to start with.
         init: Value,
@@ -631,9 +617,7 @@ impl Array {
     #[func]
     pub fn any(
         self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
         /// The function to apply to each item. Must return a boolean.
         test: Func,
@@ -651,9 +635,7 @@ impl Array {
     #[func]
     pub fn all(
         self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
         /// The function to apply to each item. Must return a boolean.
         test: Func,
@@ -831,11 +813,8 @@ impl Array {
     #[func]
     pub fn sorted(
         self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
-        /// The callsite span.
         span: Span,
         /// If given, applies this function to the elements in the array to
         /// determine the keys to sort by.
@@ -881,9 +860,7 @@ impl Array {
     #[func(title = "Deduplicate")]
     pub fn dedup(
         self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
         /// If given, applies this function to the elements in the array to
         /// determine the keys to deduplicate by.
@@ -967,9 +944,7 @@ impl Array {
     #[func]
     pub fn reduce(
         self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
         /// The reducing function. Must have two parameters: One for the
         /// accumulated value and one for an item.

crates/typst-library/src/foundations/calc.rs

@@ -97,7 +97,6 @@ cast! {
 /// ```
 #[func(title = "Power")]
 pub fn pow(
-    /// The callsite span.
     span: Span,
     /// The base of the power.
     ///
@@ -159,7 +158,6 @@ pub fn pow(
 /// ```
 #[func(title = "Exponential")]
 pub fn exp(
-    /// The callsite span.
     span: Span,
     /// The exponent of the power.
     exponent: Spanned<Num>,
@@ -412,7 +410,6 @@ pub fn tanh(
 /// ```
 #[func(title = "Logarithm")]
 pub fn log(
-    /// The callsite span.
     span: Span,
     /// The number whose logarithm to calculate. Must be strictly positive.
     value: Spanned<Num>,
@@ -454,7 +451,6 @@ pub fn log(
 /// ```
 #[func(title = "Natural Logarithm")]
 pub fn ln(
-    /// The callsite span.
     span: Span,
     /// The number whose logarithm to calculate. Must be strictly positive.
     value: Spanned<Num>,
@@ -782,7 +778,6 @@ pub fn round(
 /// ```
 #[func]
 pub fn clamp(
-    /// The callsite span.
     span: Span,
     /// The number to clamp.
     value: DecNum,
@@ -815,7 +810,6 @@ pub fn clamp(
 /// ```
 #[func(title = "Minimum")]
 pub fn min(
-    /// The callsite span.
     span: Span,
     /// The sequence of values from which to extract the minimum.
     /// Must not be empty.
@@ -833,7 +827,6 @@ pub fn min(
 /// ```
 #[func(title = "Maximum")]
 pub fn max(
-    /// The callsite span.
     span: Span,
     /// The sequence of values from which to extract the maximum.
     /// Must not be empty.
@@ -911,7 +904,6 @@ pub fn odd(
 /// ```
 #[func(title = "Remainder")]
 pub fn rem(
-    /// The span of the function call.
     span: Span,
     /// The dividend of the remainder.
     dividend: DecNum,
@@ -950,7 +942,6 @@ pub fn rem(
 /// ```
 #[func(title = "Euclidean Division")]
 pub fn div_euclid(
-    /// The callsite span.
     span: Span,
     /// The dividend of the division.
     dividend: DecNum,
@@ -994,7 +985,6 @@ pub fn div_euclid(
 /// ```
 #[func(title = "Euclidean Remainder", keywords = ["modulo", "modulus"])]
 pub fn rem_euclid(
-    /// The callsite span.
     span: Span,
     /// The dividend of the remainder.
     dividend: DecNum,
@@ -1031,7 +1021,6 @@ pub fn rem_euclid(
 /// ```
 #[func(title = "Quotient")]
 pub fn quo(
-    /// The span of the function call.
     span: Span,
     /// The dividend of the quotient.
     dividend: DecNum,

crates/typst-library/src/foundations/datetime.rs

@@ -318,7 +318,6 @@ impl Datetime {
     /// ```
     #[func]
     pub fn today(
-        /// The engine.
         engine: &mut Engine,
         /// An offset to apply to the current UTC date. If set to `{auto}`, the
         /// offset will be the local offset.

crates/typst-library/src/foundations/func.rs

@@ -334,8 +334,6 @@ impl Func {
     #[func]
     pub fn with(
         self,
-        /// The real arguments (the other argument is just for the docs).
-        /// The docs argument cannot be called `args`.
         args: &mut Args,
         /// The arguments to apply to the function.
         #[external]
@@ -361,8 +359,6 @@ impl Func {
     #[func]
     pub fn where_(
         self,
-        /// The real arguments (the other argument is just for the docs).
-        /// The docs argument cannot be called `args`.
         args: &mut Args,
         /// The fields to filter for.
         #[variadic]

crates/typst-library/src/foundations/mod.rs

@@ -266,7 +266,6 @@ impl assert {
 /// ```
 #[func(title = "Evaluate")]
 pub fn eval(
-    /// The engine.
     engine: &mut Engine,
     /// A string of Typst code to evaluate.
     source: Spanned<String>,

crates/typst-library/src/foundations/plugin.rs

@@ -152,7 +152,6 @@ impl Plugin {
     /// Creates a new plugin from a WebAssembly file.
     #[func(constructor)]
     pub fn construct(
-        /// The engine.
         engine: &mut Engine,
         /// A path to a WebAssembly file or raw WebAssembly bytes.
         ///

crates/typst-library/src/foundations/str.rs

@@ -425,9 +425,7 @@ impl Str {
     #[func]
     pub fn replace(
         &self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
         /// The pattern to search for.
         pattern: StrPattern,

crates/typst-library/src/foundations/symbol.rs

@@ -187,7 +187,6 @@ impl Symbol {
     /// ```
     #[func(constructor)]
     pub fn construct(
-        /// The callsite span.
         span: Span,
         /// The variants of the symbol.
         ///

crates/typst-library/src/foundations/target.rs

@@ -30,9 +30,6 @@ pub struct TargetElem {
 
 /// Returns the current compilation target.
 #[func(contextual)]
-pub fn target(
+pub fn target(context: Tracked<Context>) -> HintedStrResult<Target> {
-    /// The callsite context.
-    context: Tracked<Context>,
-) -> HintedStrResult<Target> {
     Ok(TargetElem::target_in(context.styles()?))
 }

crates/typst-library/src/introspection/counter.rs

@@ -428,11 +428,8 @@ impl Counter {
     #[func(contextual)]
     pub fn get(
         &self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
-        /// The callsite span.
         span: Span,
     ) -> SourceResult<CounterState> {
         let loc = context.location().at(span)?;
@@ -444,11 +441,8 @@ impl Counter {
     #[func(contextual)]
     pub fn display(
         self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
-        /// The call span of the display.
         span: Span,
         /// A [numbering pattern or a function]($numbering), which specifies how
         /// to display the counter. If given a function, that function receives
@@ -482,11 +476,8 @@ impl Counter {
     #[func(contextual)]
     pub fn at(
         &self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
-        /// The callsite span.
         span: Span,
         /// The place at which the counter's value should be retrieved.
         selector: LocatableSelector,
@@ -500,11 +491,8 @@ impl Counter {
     #[func(contextual)]
     pub fn final_(
         &self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
-        /// The callsite span.
         span: Span,
     ) -> SourceResult<CounterState> {
         context.introspect().at(span)?;
@@ -528,7 +516,6 @@ impl Counter {
     #[func]
     pub fn step(
         self,
-        /// The call span of the update.
         span: Span,
         /// The depth at which to step the counter. Defaults to `{1}`.
         #[named]
@@ -545,7 +532,6 @@ impl Counter {
     #[func]
     pub fn update(
         self,
-        /// The call span of the update.
         span: Span,
         /// If given an integer or array of integers, sets the counter to that
         /// value. If given a function, that function receives the previous

crates/typst-library/src/introspection/here.rs

@@ -44,9 +44,6 @@ use crate::introspection::Location;
 /// ```
 /// Refer to the [`selector`] type for more details on before/after selectors.
 #[func(contextual)]
-pub fn here(
+pub fn here(context: Tracked<Context>) -> HintedStrResult<Location> {
-    /// The callsite context.
-    context: Tracked<Context>,
-) -> HintedStrResult<Location> {
     context.location()
 }

crates/typst-library/src/introspection/locate.rs

@@ -24,9 +24,7 @@ use crate::introspection::Location;
 /// ```
 #[func(contextual)]
 pub fn locate(
-    /// The engine.
     engine: &mut Engine,
-    /// The callsite context.
     context: Tracked<Context>,
     /// A selector that should match exactly one element. This element will be
     /// located.

crates/typst-library/src/introspection/query.rs

@@ -136,9 +136,7 @@ use crate::foundations::{func, Array, Context, LocatableSelector, Value};
 /// ```
 #[func(contextual)]
 pub fn query(
-    /// The engine.
     engine: &mut Engine,
-    /// The callsite context.
     context: Tracked<Context>,
     /// Can be
     /// - an element function like a `heading` or `figure`,

crates/typst-library/src/introspection/state.rs

@@ -289,11 +289,8 @@ impl State {
     #[func(contextual)]
     pub fn get(
         &self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
-        /// The callsite span.
         span: Span,
     ) -> SourceResult<Value> {
         let loc = context.location().at(span)?;
@@ -309,11 +306,8 @@ impl State {
     #[func(contextual)]
     pub fn at(
         &self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
-        /// The callsite span.
         span: Span,
         /// The place at which the state's value should be retrieved.
         selector: LocatableSelector,
@@ -326,11 +320,8 @@ impl State {
     #[func(contextual)]
     pub fn final_(
         &self,
-        /// The engine.
         engine: &mut Engine,
-        /// The callsite context.
         context: Tracked<Context>,
-        /// The callsite span.
         span: Span,
     ) -> SourceResult<Value> {
         context.introspect().at(span)?;
@@ -349,7 +340,6 @@ impl State {
     #[func]
     pub fn update(
         self,
-        /// The span of the `update` call.
         span: Span,
         /// If given a non function-value, sets the state to that value. If
         /// given a function, that function receives the previous state and has

crates/typst-library/src/layout/layout.rs

@@ -54,7 +54,6 @@ use crate::layout::{BlockElem, Size};
 /// corresponding page dimension is set to `{auto}`.
 #[func]
 pub fn layout(
-    /// The call span of this function.
     span: Span,
     /// A function to call with the outer container's size. Its return value is
     /// displayed in the document.

crates/typst-library/src/layout/measure.rs

@@ -43,11 +43,8 @@ use crate::layout::{Abs, Axes, Length, Region, Size};
 /// `height`, both of type [`length`].
 #[func(contextual)]
 pub fn measure(
-    /// The engine.
     engine: &mut Engine,
-    /// The callsite context.
     context: Tracked<Context>,
-    /// The callsite span.
     span: Span,
     /// The width available to layout the content.
     ///

crates/typst-library/src/loading/cbor.rs

@@ -19,7 +19,6 @@ use crate::loading::{DataSource, Load};
 /// floating point numbers, which may result in an approximative value.
 #[func(scope, title = "CBOR")]
 pub fn cbor(
-    /// The engine.
     engine: &mut Engine,
     /// A path to a CBOR file or raw CBOR bytes.
     ///
@@ -40,7 +39,6 @@ impl cbor {
     /// directly.
     #[func(title = "Decode CBOR")]
     pub fn decode(
-        /// The engine.
         engine: &mut Engine,
         /// CBOR data.
         data: Spanned<Bytes>,

crates/typst-library/src/loading/csv.rs

@@ -25,7 +25,6 @@ use crate::loading::{DataSource, Load, Readable};
 /// ```
 #[func(scope, title = "CSV")]
 pub fn csv(
-    /// The engine.
     engine: &mut Engine,
     /// Path to a CSV file or raw CSV bytes.
     ///
@@ -102,7 +101,6 @@ impl csv {
     /// directly.
     #[func(title = "Decode CSV")]
     pub fn decode(
-        /// The engine.
         engine: &mut Engine,
         /// CSV data.
         data: Spanned<Readable>,

crates/typst-library/src/loading/json.rs

@@ -50,7 +50,6 @@ use crate::loading::{DataSource, Load, Readable};
 /// ```
 #[func(scope, title = "JSON")]
 pub fn json(
-    /// The engine.
     engine: &mut Engine,
     /// Path to a JSON file or raw JSON bytes.
     ///
@@ -71,7 +70,6 @@ impl json {
     /// directly.
     #[func(title = "Decode JSON")]
     pub fn decode(
-        /// The engine.
         engine: &mut Engine,
         /// JSON data.
         data: Spanned<Readable>,

crates/typst-library/src/loading/read.rs

@@ -24,7 +24,6 @@ use crate::World;
 /// ```
 #[func]
 pub fn read(
-    /// The engine.
     engine: &mut Engine,
     /// Path to a file.
     ///

crates/typst-library/src/loading/toml.rs

@@ -28,7 +28,6 @@ use crate::loading::{DataSource, Load, Readable};
 /// ```
 #[func(scope, title = "TOML")]
 pub fn toml(
-    /// The engine.
     engine: &mut Engine,
     /// A path to a TOML file or raw TOML bytes.
     ///
@@ -50,7 +49,6 @@ impl toml {
     /// directly.
     #[func(title = "Decode TOML")]
     pub fn decode(
-        /// The engine.
         engine: &mut Engine,
         /// TOML data.
         data: Spanned<Readable>,

crates/typst-library/src/loading/xml.rs

@@ -57,7 +57,6 @@ use crate::loading::{DataSource, Load, Readable};
 /// ```
 #[func(scope, title = "XML")]
 pub fn xml(
-    /// The engine.
     engine: &mut Engine,
     /// A path to an XML file or raw XML bytes.
     ///
@@ -83,7 +82,6 @@ impl xml {
     /// directly.
     #[func(title = "Decode XML")]
     pub fn decode(
-        /// The engine.
         engine: &mut Engine,
         /// XML data.
         data: Spanned<Readable>,

crates/typst-library/src/loading/yaml.rs

@@ -40,7 +40,6 @@ use crate::loading::{DataSource, Load, Readable};
 /// ```
 #[func(scope, title = "YAML")]
 pub fn yaml(
-    /// The engine.
     engine: &mut Engine,
     /// A path to a YAML file or raw YAML bytes.
     ///
@@ -61,7 +60,6 @@ impl yaml {
     /// directly.
     #[func(title = "Decode YAML")]
     pub fn decode(
-        /// The engine.
         engine: &mut Engine,
         /// YAML data.
         data: Spanned<Readable>,

crates/typst-library/src/math/root.rs

@@ -10,7 +10,6 @@ use crate::math::Mathy;
 /// ```
 #[func(title = "Square Root")]
 pub fn sqrt(
-    /// The call span of this function.
     span: Span,
     /// The expression to take the square root of.
     radicand: Content,

crates/typst-library/src/model/numbering.rs

@@ -53,9 +53,7 @@ use crate::text::Case;
 /// ```
 #[func]
 pub fn numbering(
-    /// The engine.
     engine: &mut Engine,
-    /// The callsite context.
     context: Tracked<Context>,
     /// Defines how the numbering works.
     ///

crates/typst-library/src/visualize/color.rs

@@ -248,8 +248,6 @@ impl Color {
     /// ```
     #[func]
     pub fn luma(
-        /// The real arguments (the other arguments are just for the docs, this
-        /// function is a bit involved, so we parse the arguments manually).
         args: &mut Args,
         /// The lightness component.
         #[external]
@@ -300,8 +298,6 @@ impl Color {
     /// ```
     #[func]
     pub fn oklab(
-        /// The real arguments (the other arguments are just for the docs, this
-        /// function is a bit involved, so we parse the arguments manually).
         args: &mut Args,
         /// The lightness component.
         #[external]
@@ -358,8 +354,6 @@ impl Color {
     /// ```
     #[func]
     pub fn oklch(
-        /// The real arguments (the other arguments are just for the docs, this
-        /// function is a bit involved, so we parse the arguments manually).
         args: &mut Args,
         /// The lightness component.
         #[external]
@@ -420,8 +414,6 @@ impl Color {
     /// ```
     #[func(title = "Linear RGB")]
     pub fn linear_rgb(
-        /// The real arguments (the other arguments are just for the docs, this
-        /// function is a bit involved, so we parse the arguments manually).
         args: &mut Args,
         /// The red component.
         #[external]
@@ -477,8 +469,6 @@ impl Color {
     /// ```
     #[func(title = "RGB")]
     pub fn rgb(
-        /// The real arguments (the other arguments are just for the docs, this
-        /// function is a bit involved, so we parse the arguments manually).
         args: &mut Args,
         /// The red component.
         #[external]
@@ -555,8 +545,6 @@ impl Color {
     /// ```
     #[func(title = "CMYK")]
     pub fn cmyk(
-        /// The real arguments (the other arguments are just for the docs, this
-        /// function is a bit involved, so we parse the arguments manually).
         args: &mut Args,
         /// The cyan component.
         #[external]
@@ -614,8 +602,6 @@ impl Color {
     /// ```
     #[func(title = "HSL")]
     pub fn hsl(
-        /// The real arguments (the other arguments are just for the docs, this
-        /// function is a bit involved, so we parse the arguments manually).
         args: &mut Args,
         /// The hue angle.
         #[external]
@@ -673,8 +659,6 @@ impl Color {
     /// ```
     #[func(title = "HSV")]
     pub fn hsv(
-        /// The real arguments (the other arguments are just for the docs, this
-        /// function is a bit involved, so we parse the arguments manually).
         args: &mut Args,
         /// The hue angle.
         #[external]
@@ -898,7 +882,6 @@ impl Color {
     #[func]
     pub fn saturate(
         self,
-        /// The call span
         span: Span,
         /// The factor to saturate the color by.
         factor: Ratio,
@@ -924,7 +907,6 @@ impl Color {
     #[func]
     pub fn desaturate(
         self,
-        /// The call span
         span: Span,
         /// The factor to desaturate the color by.
         factor: Ratio,
@@ -1001,7 +983,6 @@ impl Color {
     #[func]
     pub fn rotate(
         self,
-        /// The call span
         span: Span,
         /// The angle to rotate the hue by.
         angle: Angle,

crates/typst-library/src/visualize/gradient.rs

@@ -200,9 +200,7 @@ impl Gradient {
     /// ```
     #[func(title = "Linear Gradient")]
     pub fn linear(
-        /// The args of this function.
         args: &mut Args,
-        /// The call site of this function.
         span: Span,
         /// The color [stops](#stops) of the gradient.
         #[variadic]
@@ -292,7 +290,6 @@ impl Gradient {
     /// ```
     #[func]
     fn radial(
-        /// The call site of this function.
         span: Span,
         /// The color [stops](#stops) of the gradient.
         #[variadic]
@@ -407,7 +404,6 @@ impl Gradient {
     /// ```
     #[func]
     pub fn conic(
-        /// The call site of this function.
         span: Span,
         /// The color [stops](#stops) of the gradient.
         #[variadic]

crates/typst-library/src/visualize/image/mod.rs

@@ -112,7 +112,6 @@ impl ImageElem {
     /// ```
     #[func(title = "Decode Image")]
     pub fn decode(
-        /// The call span of this function.
         span: Span,
         /// The data to decode as an image. Can be a string for SVGs.
         data: Readable,

crates/typst-library/src/visualize/polygon.rs

@@ -67,8 +67,8 @@ impl PolygonElem {
     /// ```
     #[func(title = "Regular Polygon")]
     pub fn regular(
-        /// The call span of this function.
         span: Span,
+
         /// How to fill the polygon. See the general
         /// [polygon's documentation]($polygon.fill) for more details.
         #[named]

crates/typst-library/src/visualize/stroke.rs

@@ -97,8 +97,6 @@ impl Stroke {
     /// ```
     #[func(constructor)]
     pub fn construct(
-        /// The real arguments (the other arguments are just for the docs, this
-        /// function is a bit involved, so we parse the arguments manually).
         args: &mut Args,
 
         /// The color or gradient to use for the stroke.

crates/typst-library/src/visualize/tiling.rs

@@ -138,7 +138,6 @@ impl Tiling {
     #[func(constructor)]
     pub fn construct(
         engine: &mut Engine,
-        /// The callsite span.
         span: Span,
         /// The bounding box of each cell of the tiling.
         #[named]