docs: add docs for more mbtiles functions

[CommanderStorm]

this PR documents more of the mbtiles crate motivated by @Murtaught

[Copilot]

Pull Request Overview

This PR adds documentation for additional functions in the mbtiles crate to clarify usage and behaviors for creating and opening mbtiles databases.

• New documentation for the constructor (new) and file-opening methods (open, open_or_new, open_readonly)
• Updated comments for stream methods and tile SQL retrieval to improve clarity
• Added an example for the batch tile insertion method

Comments suppressed due to low confidence (1)

mbtiles/src/mbtiles.rs:328

• Confirm that the behavior described in the get_tile_and_hash_sql documentation has been updated intentionally. If the implementation now returns null instead of an MD5 hash, consider adding a brief note explaining the rationale for this change.

/// For [`MbtType::Flat`] accessing it is not possible, we thus return null.

[Copilot]

Pull Request Overview

This PR enriches the mbtiles crate documentation by adding and updating doc comments for several core methods and accessors, clarifying usage patterns and edge cases.

• Added docs for constructors and open methods (new, open, open_or_new, open_readonly)
• Documented accessors (filepath, filename) and operational methods (stream_coords, stream_tiles, insert_tiles)
• Updated internal method doc for SQL behavior (get_tile_and_hash_sql)

[Copilot]

The example for open_readonly is calling open_or_new. It should call open_readonly() to match the documented method.

Suggested change

	/// let conn = mbtiles.open_or_new().await.unwrap();
	/// let conn = mbtiles.open_readonly().await.unwrap();

[Copilot]

[nitpick] Raw HTML in Rustdoc can be fragile; consider using Rustdoc admonition syntax (e.g., # Warning or > **Note:**) for better readability and tooling support.

Suggested change

	/// <div class="warning">
	///
	/// **Note:** The returned [`Stream`] holds a mutable reference to the given
	/// connection, making it unusable for anything else until the stream
	/// is dropped.
	///
	/// </div>
	/// # Warning
	///
	/// **Note:** The returned [`Stream`] holds a mutable reference to the given
	/// connection, making it unusable for anything else until the stream
	/// is dropped.
	///

[nyurik]

thanks!! Great docs and great examples. In the future, we may rethink the approach to the mbtiles api - i don't think it is the most optimal at this point:

• we may want to introduce a cleaner connection state struct, i.e. MbtilesConnection, which will internally know the detected type of the file - so it won't need to be passed around
• we may want to modify insert_tiles to take &[u8] instead of Vec<u8>

and maybe other refactorings. Current api was tailored to Martin's internal usage, and was never really targeting broader usecases.