mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-18 02:32:33 +00:00
Lints: unambiguous write doc links, private doc links, contains
This commit is contained in:
@@ -5,7 +5,7 @@ use std::io::Write;
|
||||
use crate::chunk::{AepFile, Body, Chunk};
|
||||
use crate::error::AepError;
|
||||
|
||||
/// Deepest tree [`write`] accepts (a hand-built tree may be deeper than any parsed one).
|
||||
/// Deepest tree [`fn@write`] accepts (a hand-built tree may be deeper than any parsed one).
|
||||
const MAX_WRITE_DEPTH: usize = 256;
|
||||
|
||||
/// Serialises `file`: `RIFX`, the recomputed container size, `Egg!`, the chunks and the trailer.
|
||||
@@ -39,10 +39,10 @@ pub fn write(file: &AepFile<'_>) -> Result<Vec<u8>, AepError> {
|
||||
Ok(out)
|
||||
}
|
||||
|
||||
/// Like [`write`], into any writer.
|
||||
/// Like [`fn@write`], into any writer.
|
||||
///
|
||||
/// # Errors
|
||||
/// A size or depth error of [`write`] becomes `ErrorKind::InvalidData`; otherwise I/O errors.
|
||||
/// A size or depth error of [`fn@write`] becomes `ErrorKind::InvalidData`; otherwise I/O errors.
|
||||
pub fn write_to(file: &AepFile<'_>, w: &mut impl Write) -> std::io::Result<()> {
|
||||
let bytes = write(file).map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
|
||||
w.write_all(&bytes)
|
||||
|
||||
@@ -300,7 +300,7 @@ fn parse_unbounded(bytes: &[u8], format: Format) -> Result<Document> {
|
||||
}
|
||||
}
|
||||
|
||||
/// Options for [`write`].
|
||||
/// Options for [`fn@write`].
|
||||
#[derive(Clone, Copy, Debug)]
|
||||
pub struct WriteOptions {
|
||||
/// SCC / MCC: drop-frame timecode (the usual choice for 29.97 fps).
|
||||
@@ -456,7 +456,7 @@ fn lossy_chars(
|
||||
}
|
||||
}
|
||||
|
||||
/// [`write`] into `out`. MCC goes out line by line, so a long `every_frame_until` export is never
|
||||
/// [`fn@write`] into `out`. MCC goes out line by line, so a long `every_frame_until` export is never
|
||||
/// held in memory; the other formats are small and written whole.
|
||||
pub fn write_to(out: &mut dyn std::io::Write, doc: &Document, format: Format, opts: WriteOptions) -> std::io::Result<()> {
|
||||
match format {
|
||||
|
||||
@@ -215,7 +215,7 @@ fn encode_text(text: &str) -> Vec<u8> {
|
||||
encode_text_noting(text, &mut Vec::new())
|
||||
}
|
||||
|
||||
/// The characters of `text` that ISO/IEC 6937 has no code for, in order: [`write`] sends each
|
||||
/// The characters of `text` that ISO/IEC 6937 has no code for, in order: [`fn@write`] sends each
|
||||
/// as `?`.
|
||||
pub fn unencodable(text: &str) -> Vec<char> {
|
||||
let mut lost = Vec::new();
|
||||
@@ -393,7 +393,7 @@ fn put(buf: &mut [u8], at: usize, len: usize, s: &str) {
|
||||
}
|
||||
}
|
||||
|
||||
/// The frame rate and disk format code [`write`] uses for a programme at `rate`: 29.97 fps
|
||||
/// The frame rate and disk format code [`fn@write`] uses for a programme at `rate`: 29.97 fps
|
||||
/// (`STL30.01`) for 29.97 and 30, else 25 fps (`STL25.01`).
|
||||
fn file_rate(rate: Option<FrameRate>) -> (FrameRate, &'static str) {
|
||||
match rate {
|
||||
@@ -402,7 +402,7 @@ fn file_rate(rate: Option<FrameRate>) -> (FrameRate, &'static str) {
|
||||
}
|
||||
}
|
||||
|
||||
/// The time code [`write`] gives a caption starting at `t` in a programme at `rate`.
|
||||
/// The time code [`fn@write`] gives a caption starting at `t` in a programme at `rate`.
|
||||
pub fn timecode(t: Tick, rate: Option<FrameRate>) -> String {
|
||||
let (rate, _) = file_rate(rate);
|
||||
let (_, h, m, s, f) = frames_to_fields(rate.frame_at(rate.snap_nearest(t)), rate, false);
|
||||
@@ -488,7 +488,7 @@ fn split_tf(text: &[u8]) -> Vec<&[u8]> {
|
||||
out
|
||||
}
|
||||
|
||||
/// Frame of `t` on the STL grid of `rate` (see [`write`]).
|
||||
/// Frame of `t` on the STL grid of `rate` (see [`fn@write`]).
|
||||
pub fn frame_of(t: Tick, rate: FrameRate) -> i64 {
|
||||
rate.frame_at(rate.snap_nearest(t))
|
||||
}
|
||||
|
||||
@@ -46,7 +46,7 @@ pub fn split_voice(text: &str) -> (Option<String>, String) {
|
||||
(None, text.to_string())
|
||||
}
|
||||
|
||||
/// Undo [`write`]'s cue-text escape, so `A --> B` comes back as `A --> B` and not `A --> B`.
|
||||
/// Undo [`fn@write`]'s cue-text escape, so `A --> B` comes back as `A --> B` and not `A --> B`.
|
||||
///
|
||||
/// Only the one substitution the writer makes is reversed: a literal `-->` in cue text would read
|
||||
/// as a timing line to anything scanning the block, so it is written `-->`. Other entities
|
||||
@@ -55,7 +55,7 @@ fn unescape_text(text: &str) -> String {
|
||||
rewrite_arrows(text, false)
|
||||
}
|
||||
|
||||
/// Apply [`write`]'s cue-text escape. `-->` becomes `-->`, and a literal `-->` (or the same
|
||||
/// Apply [`fn@write`]'s cue-text escape. `-->` becomes `-->`, and a literal `-->` (or the same
|
||||
/// with more `&` in front of `gt;`) gains one `&`, so the escape is reversible.
|
||||
fn escape_text(text: &str) -> String {
|
||||
rewrite_arrows(text, true)
|
||||
|
||||
@@ -52,7 +52,7 @@ pub struct Spec<'a> {
|
||||
pub legacy_assets_field: Option<&'a str>,
|
||||
}
|
||||
|
||||
/// An embedded asset passed to [`write`].
|
||||
/// An embedded asset passed to [`fn@write`].
|
||||
#[derive(Clone, Copy, Debug)]
|
||||
pub struct Asset<'a> {
|
||||
/// Decimal asset id used in the archive entry path.
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
//! naming the package document (OPF), which lists every resource in its manifest and the reading
|
||||
//! order in its spine, and (EPUB 3) a navigation document.
|
||||
//!
|
||||
//! - [`write`] turns a [`Book`] (metadata, resources, spine, navigation) into an EPUB 3 package,
|
||||
//! - [`fn@write`] turns a [`Book`] (metadata, resources, spine, navigation) into an EPUB 3 package,
|
||||
//! reflowable or fixed layout. The content documents are the caller's: this crate packages
|
||||
//! them, it does not make XHTML out of a document model ([`xhtml`] is only the shell).
|
||||
//! - [`Epub::open`] reads an EPUB 2 or 3 package: container, metadata, manifest and spine, with
|
||||
@@ -46,7 +46,7 @@ pub enum Error {
|
||||
/// The archive has more entries than [`Limits::max_entries`].
|
||||
#[error("the EPUB package has {found} entries (at most {limit})")]
|
||||
TooManyEntries { found: usize, limit: usize },
|
||||
/// The book given to [`write`] cannot be a valid package.
|
||||
/// The book given to [`fn@write`] cannot be a valid package.
|
||||
#[error("invalid EPUB book: {0}")]
|
||||
Invalid(String),
|
||||
}
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
//! sample type, over the part's data window. Every compression the `exr` crate reads is read,
|
||||
//! scan lines and tiles alike (the largest resolution level). Other parts' chunks are skipped
|
||||
//! unread, and channels the filter drops are never allocated.
|
||||
//! - [`write`] writes one scan-line part.
|
||||
//! - [`fn@write`] writes one scan-line part.
|
||||
//!
|
||||
//! The `exr` crate sizes buffers from headers before it reads pixels, so everything that reaches
|
||||
//! it is checked first: preview attributes against their own size, each part's samples against
|
||||
@@ -44,7 +44,7 @@ pub enum Error {
|
||||
/// The file declares more than [`Limits`] allow.
|
||||
#[error("OpenEXR exceeds a limit: {0}")]
|
||||
LimitExceeded(String),
|
||||
/// The picture handed to [`write`] cannot be stored.
|
||||
/// The picture handed to [`fn@write`] cannot be stored.
|
||||
#[error("OpenEXR: cannot write: {0}")]
|
||||
Encode(String),
|
||||
}
|
||||
@@ -747,7 +747,7 @@ pub fn decode_part(bytes: &[u8], index: usize, keep: &dyn Fn(&str) -> bool, limi
|
||||
Ok(Part { info, channels })
|
||||
}
|
||||
|
||||
/// Compression for [`write`].
|
||||
/// Compression for [`fn@write`].
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
|
||||
pub enum Compression {
|
||||
None,
|
||||
|
||||
@@ -599,7 +599,7 @@ pub fn write(scene: &Scene, mtllib: Option<&str>, limits: &Limits) -> Result<Str
|
||||
Ok(text)
|
||||
}
|
||||
|
||||
/// The scene's materials as an MTL library, named as [`write`] names them: `Kd`, `d`, `Ke`,
|
||||
/// The scene's materials as an MTL library, named as [`fn@write`] names them: `Kd`, `d`, `Ke`,
|
||||
/// `Ns` (for readers without the PBR extension) with `Pr` and `Pm`, and `map_Kd`, `map_Ke`
|
||||
/// and `norm` for images that have a [`Image::uri`].
|
||||
pub fn write_mtl(scene: &Scene) -> String {
|
||||
|
||||
@@ -734,7 +734,7 @@ fn thumbnail_range(order: Order, body: &[u8], ptr: usize) -> Option<(usize, usiz
|
||||
}
|
||||
|
||||
/// The EXIF to write next to upright pixels at resolution `ppi`: Orientation 1 (see
|
||||
/// [`upright_exif`]), no thumbnail of the source image (see [`exif_without_thumbnail`]) and,
|
||||
/// [`upright_exif`]), no thumbnail of the source image (see `exif_without_thumbnail`) and,
|
||||
/// when `ppi` is known, the resolution (see [`exif_with_resolution`]).
|
||||
pub fn export_exif(exif: &[u8], ppi: Option<(f32, f32)>) -> Cow<'_, [u8]> {
|
||||
export_exif_inner(exif, ppi, false)
|
||||
|
||||
@@ -356,7 +356,7 @@ pub fn from_embedded(e: &Embedded) -> Metadata {
|
||||
}
|
||||
|
||||
/// The XMP of `e` read as one packet: the standard packet, with the Extended XMP it links to
|
||||
/// (`xmpNote:HasExtendedXMP`) merged in (see [`xmp::parse_xmp_pair`]). An error when the standard
|
||||
/// (`xmpNote:HasExtendedXMP`) merged in (see `xmp::parse_xmp_pair`). An error when the standard
|
||||
/// packet is not XMP, when its link is malformed, when the linked extension is missing or
|
||||
/// unreadable ([`Embedded::xmp_extended_error`]), or when there is an extension nothing links to:
|
||||
/// a caller that must see all of a file's metadata (to prove it carries no location, say) refuses
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
//! - [`markers`] lists a JPEG's marker segments before the first scan, for the APPn payloads this
|
||||
//! crate does not interpret itself (for example ISO 21496-1 gain map metadata in APP2).
|
||||
//! - [`images`] lists the images after the primary one, with their file offsets.
|
||||
//! - [`write`] puts an index into a primary JPEG and appends the other images to it.
|
||||
//! - [`fn@write`] puts an index into a primary JPEG and appends the other images to it.
|
||||
|
||||
use craft_tiff::{ByteOrder, Tiff};
|
||||
|
||||
@@ -39,7 +39,7 @@ pub struct MpfImage {
|
||||
pub kind: u32,
|
||||
}
|
||||
|
||||
/// Why [`write`] refused.
|
||||
/// Why [`fn@write`] refused.
|
||||
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
||||
pub enum MpfError {
|
||||
/// The primary image does not start with a JPEG SOI marker, or its segments cannot be walked.
|
||||
|
||||
@@ -60,7 +60,7 @@ pub const MIN_PASSWORD_CHARS: usize = 8;
|
||||
|
||||
/// The most key-derivation work one [`open`] does, in hash blocks summed over every derivation
|
||||
/// in the file. The file names its own iteration counts, so without a budget a crafted file
|
||||
/// hangs the caller on the password check. A file written by [`write`] needs about
|
||||
/// hangs the caller on the password check. A file written by [`fn@write`] needs about
|
||||
/// 2 million; real files from other tools need far less.
|
||||
const OPEN_BUDGET: u64 = 10_000_000;
|
||||
|
||||
|
||||
@@ -54,7 +54,7 @@ impl Clipboard {
|
||||
self.synthetic = synthetic;
|
||||
}
|
||||
|
||||
/// Puts `text` on the clipboard as a plain-text flavor; see [`write`](Self::write).
|
||||
/// Puts `text` on the clipboard as a plain-text flavor; see [`fn@write`](Self::write).
|
||||
pub fn write_text(&mut self, text: &str) -> Result<Written, ClipboardError> {
|
||||
self.write(&[Flavor::text(text)])
|
||||
}
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
//! L*/100 followed by a* and b*. Unknown colour models and block types are kept verbatim
|
||||
//! (colour models) or skipped (block types). Converting colours is the caller's job.
|
||||
//!
|
||||
//! [`parse`] and [`write`] keep what the file says. The reading rules an application applies
|
||||
//! [`parse`] and [`fn@write`] keep what the file says. The reading rules an application applies
|
||||
//! when it shows a file's swatches are separate, so each can choose them:
|
||||
//! [`AseColor::lab_lightness`] (some writers store L* itself), [`AseColor::value_name`] (names
|
||||
//! for unnamed colours, as new swatches are named) and [`AseFile::apply_names`] with
|
||||
|
||||
@@ -31,7 +31,7 @@
|
||||
//! they are.
|
||||
//!
|
||||
//! [`parse`] never panics: every count is bounds-checked against the bytes left, descriptor
|
||||
//! nesting is bounded, and allocations are capped. [`write`] always produces version 16, so
|
||||
//! nesting is bounded, and allocations are capped. [`fn@write`] always produces version 16, so
|
||||
//! `parse(write(f)) == f` for sets [`parse`] read. The existing single-set API retains trailing-byte
|
||||
//! warnings. [`parse_sets`] and [`write_sets`] preserve complete version-16 multi-set files with
|
||||
//! one version header; a version-12 file's legacy descriptors keep their meaning, not their layout.
|
||||
@@ -134,7 +134,7 @@ pub struct AtnFile {
|
||||
/// "macintosh"…): the one given to [`parse_with_encoding`], else the one that turns such
|
||||
/// names into the Unicode class names stored with them, else a guess from the names shown
|
||||
/// from their bytes alone. `None` when there are no such names, or nothing tells and no
|
||||
/// name depends on it. [`write`] ignores it: names are written as stored.
|
||||
/// name depends on it. [`fn@write`] ignores it: names are written as stored.
|
||||
#[cfg_attr(feature = "serde", serde(default))]
|
||||
pub encoding: Option<String>,
|
||||
}
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
//! arrays `[ … ]`, strings `( … )` holding UTF-16BE with a `FE FF` byte-order mark and `\`
|
||||
//! escapes, numbers (`12`, `-1.5`, `.5`), `true`/`false`, and `/Name` values.
|
||||
//!
|
||||
//! [`parse`] and [`write`] keep the document as a tree of [`Value`]s; what was parsed is written
|
||||
//! [`parse`] and [`fn@write`] keep the document as a tree of [`Value`]s; what was parsed is written
|
||||
//! back in Photoshop's layout, and strings stored as plain bytes stay plain bytes.
|
||||
//! [`first_style`] is a typed view of the first style run, for readers that show a type layer
|
||||
//! without editing it; [`parse_lossy`] reads what it can of a damaged document for them.
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
//! - [`TextDecoder`] and [`codepage`]: text in the file's code pages, `\uN` with its fallback
|
||||
//! characters and surrogate pairs. [`esc`] goes the other way. [`dttm_to_iso`],
|
||||
//! [`iso_to_dttm`], [`date_words`] and [`iso_date`] are RTF's two date forms.
|
||||
//! - [`read`] and [`write`]: a file to and from a small neutral model ([`Document`]):
|
||||
//! - [`read`] and [`fn@write`]: a file to and from a small neutral model ([`Document`]):
|
||||
//! paragraphs with outline level, alignment, indents and spacing, runs with bold, italic,
|
||||
//! underline, strikethrough, superscript and subscript, size, colour and font, and tables.
|
||||
//!
|
||||
|
||||
@@ -142,7 +142,7 @@ fn jobs(options: &Options) -> Vec<Job> {
|
||||
let catalog = Catalog::linked();
|
||||
let mut jobs = Vec::new();
|
||||
for component in &catalog.components {
|
||||
if options.only.as_ref().is_some_and(|only| !only.iter().any(|name| *name == component.name)) {
|
||||
if options.only.as_ref().is_some_and(|only| !only.contains(&component.name)) {
|
||||
continue;
|
||||
}
|
||||
let Some(entry) = entry_of(component.type_name) else { continue };
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
//! [`parse`] gives the list as written ([`Edl`]: events of lines with their timecode fields); what
|
||||
//! an event means on a timeline (which media a reel is, how a dissolve overlaps) is the caller's
|
||||
//! mapping. A list carries no frame rate: [`guess_rate`] guesses one, and [`Timecode::frames`]
|
||||
//! counts at the rate the caller settles on. [`write`] lays out events the caller built.
|
||||
//! counts at the rate the caller settles on. [`fn@write`] lays out events the caller built.
|
||||
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
|
||||
|
||||
use std::collections::BTreeSet;
|
||||
|
||||
Reference in New Issue
Block a user