1.0 checklist

[CAD97]

This is a meta issue tracking concerns that have been raised and should be addressed before publishing a 1.0 version. Once all of the checkboxes here are checked, we should be good for a 1.0 release.

• Should TextSize::of use APIT or an explicit generic? (IOW, should TextSize::of::<&str>(s) be allowed? Using this form would allow deref coercion to kick in.)
  • Related, should we provide a deref-coercion-like recursive impl for TextSized?
• Should TextSized get a "uglier" name, as it is not meant to be used directly? (And TextSized/TextSize are very close names.)
  • LenTextSize::len_text_size has been proposed.
• TextRange::empty(offset) or TextRange::empty() (and thus TextRange::empty() + offset to get the offset behavior)?

API Guidelines

• Naming (crate aligns with Rust naming conventions)
  • Casing conforms to RFC 430 (C-CASE)
  • Ad-hoc conversions follow as_, to_, into_ conventions (C-CONV)
  • Getter names follow Rust convention (C-GETTER)
  • Methods on collections that produce iterators follow iter, iter_mut, into_iter (C-ITER)
  • Iterator type names match the methods that produce them (C-ITER-TY)
  • Feature names are free of placeholder words (C-FEATURE)
  • Names use a consistent word order (C-WORD-ORDER)
• Interoperability (crate interacts nicely with other library functionality)
  • Types eagerly implement common traits (C-COMMON-TRAITS)
    • Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug,
      Display, Default
  • Conversions use the standard traits From, AsRef, AsMut (C-CONV-TRAITS)
  • Collections implement FromIterator and Extend (C-COLLECT)
  • Data structures implement Serde's Serialize, Deserialize (C-SERDE)
  • Types are Send and Sync where possible (C-SEND-SYNC)
  • Error types are meaningful and well-behaved (C-GOOD-ERR)
  • Binary number types provide Hex, Octal, Binary formatting (C-NUM-FMT)
  • Generic reader/writer functions take R: Read and W: Write by value (C-RW-VALUE)
• Macros (crate presents well-behaved macros)
  • Input syntax is evocative of the output (C-EVOCATIVE)
  • Macros compose well with attributes (C-MACRO-ATTR)
  • Item macros work anywhere that items are allowed (C-ANYWHERE)
  • Item macros support visibility specifiers (C-MACRO-VIS)
  • Type fragments are flexible (C-MACRO-TY)
• Documentation (crate is abundantly documented)
  • Crate level docs are thorough and include examples (C-CRATE-DOC)
  • All items have a rustdoc example (C-EXAMPLE)
  • Examples use ?, not try!, not unwrap (C-QUESTION-MARK)
  • Function docs include error, panic, and safety considerations (C-FAILURE)
  • Prose contains hyperlinks to relevant things (C-LINK)
  • Cargo.toml includes all common metadata (C-METADATA)
    • authors, description, license, homepage, documentation, repository,
      readme, keywords, categories
  • Crate sets html_root_url attribute "https://docs.rs/CRATE/X.Y.Z" (C-HTML-ROOT)
  • Release notes document all significant changes (C-RELNOTES)
  • Rustdoc does not show unhelpful implementation details (C-HIDDEN)
• Predictability (crate enables legible code that acts how it looks)
  • Smart pointers do not add inherent methods (C-SMART-PTR)
  • Conversions live on the most specific type involved (C-CONV-SPECIFIC)
  • Functions with a clear receiver are methods (C-METHOD)
  • Functions do not take out-parameters (C-NO-OUT)
  • Operator overloads are unsurprising (C-OVERLOAD)
  • Only smart pointers implement Deref and DerefMut (C-DEREF)
  • Constructors are static, inherent methods (C-CTOR)
• Flexibility (crate supports diverse real-world use cases)
  • Functions expose intermediate results to avoid duplicate work (C-INTERMEDIATE)
  • Caller decides where to copy and place data (C-CALLER-CONTROL)
  • Functions minimize assumptions about parameters by using generics (C-GENERIC)
  • Traits are object-safe if they may be useful as a trait object (C-OBJECT)
• Type safety (crate leverages the type system effectively)
  • Newtypes provide static distinctions (C-NEWTYPE)
  • Arguments convey meaning through types, not bool or Option (C-CUSTOM-TYPE)
  • Types for a set of flags are bitflags, not enums (C-BITFLAG)
  • Builders enable construction of complex values (C-BUILDER)
• Dependability (crate is unlikely to do the wrong thing)
  • Functions validate their arguments (C-VALIDATE)
  • Destructors never fail (C-DTOR-FAIL)
  • Destructors that may block have alternatives (C-DTOR-BLOCK)
• Debuggability (crate is conducive to easy debugging)
  • All public types implement Debug (C-DEBUG)
  • Debug representation is never empty (C-DEBUG-NONEMPTY)
• Future proofing (crate is free to improve without breaking users' code)
  • Sealed traits protect against downstream implementations (C-SEALED)
  • Structs have private fields (C-STRUCT-PRIVATE)
  • Newtypes encapsulate implementation details (C-NEWTYPE-HIDE)
  • Data structures do not duplicate derived trait bounds (C-STRUCT-BOUNDS)
• Necessities (to whom they matter, they really matter)
  • Public dependencies of a stable crate are stable (C-STABLE)
  • Crate and its dependencies have a permissive license (C-PERMISSIVE)

[matklad]

I'd also try to think of a better name for offset_len. In https://github.com/CAD97/rowan/pull/3/files, up_to is used only as a part of + offset pattern....

And maybe to re-thing the fn TextRange hack. TextRange::new would be a boring equivalent

TextRange::new(start, end);
TextRange::with_len(start, len);
TextRange::offset_len(start, len);

[matklad]

Argh, its excruciating, C# uses ::new(start, len), and they get to use ::from_bounds for the other ctor. But I do believe that from_bounds should be the canonical ctor (it's twice as frequent as offset_len in rust-analyzer).

[CAD97]

The PRs I just opened address all of the remaining specific concerns.

After that is just making sure that we're happy with our state against the API guidelines, and then we're good to release. (Though it may be still worth it to release as 0.99, so if we find anything while updating rowan and rust-analyzer for real, we still have the flexibility to make more changes.)

[matklad]

I do feel that we should do 0.99, update rowan and ra, and then do 1.0

[CAD97]

For visibility, the API guidelines I haven't checked off yet:

• Documentation (crate is abundantly documented)
  • Crate level docs are thorough and include examples (C-CRATE-DOC)
  • All items have a rustdoc example (C-EXAMPLE)
  • Function docs include error, panic, and safety considerations (C-FAILURE)
  • Prose contains hyperlinks to relevant things (C-LINK)
  • Cargo.toml includes all common metadata (C-METADATA)
    • authors, description, license, homepage, documentation, repository,
      readme, keywords, categories
  • Crate sets html_root_url attribute "https://docs.rs/CRATE/X.Y.Z" (C-HTML-ROOT)
  • Release notes document all significant changes (C-RELNOTES)
• Future proofing (crate is free to improve without breaking users' code)
  • Sealed traits protect against downstream implementations (C-SEALED)

I think:

• We could use some crate-level docs at least, maybe explaining the benefit of using TextSize/TextRange over usize/ops::Range<usize>?
• Small examples are hard.
• Do we need to add more error/panic/safety considerations? We do have some panicking cases without explicit # Panics docs sections, such as <&str as LenTextSize>::len_text_size (and thus TextSize::of).
• I think I've made sure relevant things are always linked?
• We don't have a homepage, so that's out. Readme, keywords, and categories should be set.
• C-HTML-ROOT is obsolete
• We should probably keep a changelog, even if it only starts with version 0.99.
• LenTextSized might want to be sealed, we just need to make that decision explicitly (again?).

And the final concern: mark text-unit as deprecated and point users at text-size.

[matklad]

TBH, I feel like only the changelog would add significant value here. It's not like TextSize will become a super foundational crate which requires rigorous approach to maintainence.

But it probably makes sense to add a top-level doc along the lines of "unless you plan to pervasively use and store TextRanges, prefer to forumalte your crate's API in terms of ranges of usize". I.e, I worry more that the crate will be missued. I've recently seen a blog post about lexers, which used text-size, which I think is a missuse -- a generic lexer has noting to gain (and generality and interop to loose) from switching to text-size.

[matklad]

ping @CAD97 what are our further action items here? I think just migrating rowan and rust-analyzer to 0.99? Would be willing to try this out?

[matklad]

gentle re-ping @CAD97 (:

[CAD97]

Concrete things I'd like to see:

• A changelog somewhere. This should be the proper home of the text_unit => text-size translation tables, rather than directly in the docs. (Also, I forgot to change the translation table for the from_len => at rename.)
• Crate level docs (and readme) discuss when to (not) use the crate.
• Missing Cargo metadata should be added (readme, keywords, categories).
• Redo the rowan and r-a ports as a final sanity check. I'm doing this now.

[matklad]

This should be the proper home of the text_unit => text-size translation tables, rather than directly in the docs

I believe the cumulative value of the transition table in the docs over the lifetime will be negative, so yeah, we should put it into a changelog (or just remove altogether, I think it's intuitive enough)

[CAD97]

rowan patch: CAD97/rowan#3
ra-patch: CAD97/rust-analyzer#1

Notes, again:

• We might want a smol-str update that does impl TextLen for &'_ SmolStr.
• maybe provide usize as From<&TextSize> as well?
• cargo insta review is a blessing for widespread trivial changes like changing the formatting of TextRange which changes the format of literally every snapshot test in r-a; can we have that for the remaining tests yesterday so I don't have to go and fix every one manually please
  
  
  this is after getting as far as I can with INSTA_UPDATE=always cargo test --workspace
• I did fix every test with search&replace and I should have put it in a separate commit but I really don't want to redo it
• because it was painful and not even perfectly accurate the first time and had to be cleaned up manually afterwards
• we need to get directory-sniffing tests into insta proper so cargo insta review works for them

[CAD97]

Adding glob based parameterized tests into insta ended up being easier than I initially expected and ran into the first time: mitsuhiko/insta#109

[matklad]

can we have that for the remaining tests yesterday

I am not sure what are you trying to say here, but, if you don't feel like updating the tests, I certainly can do this myself!

[CAD97]

Mainly that there are a number of tests (read: every single .rast test) that are not updated by doing cargo insta test --accept (or any of the other ways to bless insta tests) and if there's a way to bless them, it's not clear to me. I did update all the .rast tests with a regex, but it broke and didn't work in some cases that I had to fix manually.

It'd be awesome to get the .rast tests using insta as well so cargo insta review just works, and to that end I've opened a PR against insta adding the needed glob-based test discovery.

It would have saved me a lot of effort had the tests been using insta already. (Now if you do want to help make the patch better, separating the actual code changes from the test updates really should be done.)

I'm happy publishing 0.99 once we have moved the text_unit translation tables to a changelog and added "when to use this" documentation. (Both of which I'd rather you write tbh :stuck_out_tounge: )

[matklad]

and if there's a way to bless them, it's not clear to me.

Aha, there's indeed a way: https://github.com/rust-analyzer/rust-analyzer/blob/779555c1beac90f633c01a773558c4007c99c97f/crates/test_utils/src/lib.rs#L398

[matklad]

Published 0.99

[matklad]

cc @BurntSushi, this is tangentially related to your work in text search area:

We publishing the 1.0 crate with "vocabulary" types for text offsets (struct TextSize(u32)) and text ranges (struct TextRange(u32, u32)). These types might be useful for cases like IDEs and text editors, but are explicitly not intended for general low-level utilites like regex engines or lexers (this is called out in the docs).

No action is expected, this is just to let you know that the thing exists :)

[matklad]

@CAD97 is some work here blocked on me? Are we ready to basically just swithc rust-analyzer to this?

[CAD97]

Yeah, the remaining steps are to update r-a to the version of rowan using 0.99, then assuming everything works, publish 1.0, update rowan to use it, update r-a to use that version of rowan.

[matklad]

Good, I'll do this now

[matklad]

1.0 is published!