Audit API naming

[joshlf]

Progress

• FromBytes::ref_from_prefix inconsistent with FromBytes::from_prefix_with_trailing_elements?
  • [FromBytes] Rename some methods for consistency #1210
• Finalize naming as outlined in Revising the (`Try`)`FromBytes` Conversion Methods in 0.8 #1095
• Consider replacing with_trailing_elements with with_elems in method names
  • Rename FromBytes methods using with_elems suffix #1245
• Finalize all #[doc(hidden)] pub functions/methods - finalize naming or delete
• Add methods with old names, marked #[doc(hidden)] and #[deprecated]
• Audit to make sure that all deprecation messages mention the current names (since names have changed somewhat since some #[deprecated] attributes were added)
• Resolve all TODO(#871) comments
• Does the name Ref::from cause inference issues since Rust thinks it might be From::from rather than inherent?
  • Add Ref more with_elems Ref constructors #1258
• Rename Ref::unaligned_from to unaligned_from_bytes
  • Rename FromBytes::ref_from[_with_elems] #1278
• Rename FromBytes::ref_from[_with_elems] to ref_from_bytes[_with_elems]
  • Rename FromBytes::ref_from[_with_elems] #1278
• Rename FromBytes::read_from to read_from_bytes?
• Audit TryFromBytes methods for naming consistency w/ FromBytes methods
  • Rename TryFromBytes methods for consistency with FromBytes #1475
• Make deprecated Ref methods return Options instead of Results (ie, consistent with old signatures)?

Details

In the same vein as #253, we should audit our API for:

• Internal consistency
• Consistency with existing conventions

Also see #284, the "Naming" section of #1095

[jswrenn]

I have a scratchpad of name correspondences here: https://docs.google.com/spreadsheets/d/1o_ll7S3iW7xe3UdG_t8hzjBmUD-uRHXKyxZXJ7i1D2g/edit?usp=sharing

We do have some minor naming inconsistencies between Ref and FromBytes. For example, FromBytes::{mut_from_prefix,ref_from_prefix} corresponds to Ref::new_from_prefix. The pattern here, which holds for many other such methods, is that one drops the mut/ref and replaces it with new.

This pattern does not apply to FromBytes::{mut_from,ref_from}. The pattern suggests a correspondence to Ref::new_from, but it actually corresponds to Ref::new.

As a point of brevity: I wonder if we should drop the new_ prefixes. They're abundant and redundant — the fact that these are constructed a Ref is already denoted by from.

The placement of unaligned and zeroed in the Ref names is awkward. Why new_slice_unaligned_from_prefix and not new_unaligned_slice_from_prefix (i.e., adjective preceding the noun)?

[joshlf]

Also: When we add KnownLayout APIs in #996, we need to bikeshed their names too.

[jswrenn]

Re. the count-taking methods: Current contenders include _with_trailing_elements and _with_count. These result in identifiers of up to 39 characters long (mut_from_prefix_with_trailing_elements) and 27 characters long (mut_from_prefix_with_count), respectively.

Personally, I'm inclined towards the briefer option. I'd also argument that with_trailing_elements is a misnomer; these methods don't consume trailing elements, they consume a count of the trailing elements.

For even more bevity, we could even do:

$ echo {,count_}{mut,ref}_from{,_prefix,_suffix} | tr ' ' '\n' 
mut_from_prefix
mut_from_suffix
ref_from
ref_from_prefix
ref_from_suffix
count_mut_from
count_mut_from_prefix
count_mut_from_suffix
count_ref_from
count_ref_from_prefix
count_ref_from_suffix

The longest identifier here is only 22 characters long. Personally, I'm a little attached to having all of our identifiers on FromBytes start with either ref or mut.

[joshlf]

Discussed offline, and decided to go with xxx_with_elems for methods that take a trailing slice element count.