Skip to content

Fix doc warnings #2305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Fix doc warnings #2305

wants to merge 2 commits into from

Conversation

mamcx
Copy link
Contributor

@mamcx mamcx commented Feb 25, 2025 •
edited
Loading

Description of Changes

Fix as many warnings caused by cargo doc.

Some that stay:

  • Of the form warning: public documentation for X links to private item Y
  • The top doc on crates/core/src/subscription/subscription.rs This generate unresolved link warnings but looks to me that need a full rewrite c.c. @joshua-spacetime.

Expected complexity level and risk

0

Testing

  • Run cargo doc --all. Because we have a naming collision:
Error: document output filename collision
The lib `spacetimedb` in package `spacetimedb-core v1.0.0-rc4 (.../space/SpacetimeDB/crates/core)` has the same name as the lib `spacetimedb` in package `spacetimedb v1.0.0-rc4 (../space/SpacetimeDB/crates/bindings)`.
Only one may be documented at once since they output to the same path.

... then I switch adding doc =false in each to let me see all the warnings.

@mamcx mamcx added documentation Improvements or additions to documentation release-any To be landed in any release window labels Feb 25, 2025
@mamcx mamcx self-assigned this Feb 25, 2025
mamcx
mamcx commented Feb 25, 2025
View reviewed changes
crates/core/src/subscription/query.rs
@@ -25,7 +25,7 @@ pub const SUBSCRIBE_TO_ALL_QUERY: &str = "SELECT * FROM *";
/// rather than returning a new `SourceSet`.
///
/// This is necessary when merging multiple SQL queries into a single query set,
/// as in [`crate::subscription::module_subscription_actor::ModuleSubscriptions::add_subscriber`].
/// as in [`crate::subscription::module_subscription_actor::ModuleSubscriptions::add_multi_subscription`].
pub fn compile_read_only_queryset(
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I not sure if this is correct.

crates/sdk/tests/connect_disconnect_client/src/module_bindings/mod.rs Outdated
@@ -535,7 +535,7 @@ impl __sdk::DbContext for ReducerEventContext {

impl __sdk::ReducerEventContext for ReducerEventContext {}

/// An [`__sdk::DbContext`] passed to [`__sdk::SubscriptionBuilder::on_applied`] and [`SubscriptionHandle::unsubscribe_then`] callbacks.
/// An [`__sdk::DbContext`] passed to subscription callbacks.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are many more now.

crates/sqltest/src/main.rs
@@ -327,7 +327,7 @@ async fn update_test_files(files: Vec<PathBuf>, engine: DbType, format: bool) ->
Ok(())
}

/// Different from [`sqllogictest::update_test_file`], we re-implement it here to print some
/// Different from [`sqllogictest`], we re-implement logic here to print some
/// progress information.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The original impl is not there, but this is fine, this only internal and nobody else use it.

crates/vm/src/expr.rs
@@ -620,8 +620,6 @@ impl SourceExpr {
/// If `self` refers to a [`DbTable`], get a reference to it.
///
/// Returns `None` if `self` refers to a [`MemTable`].
/// In that case, retrieving the [`MemTable`] requires inspecting the plan's corresponding [`SourceSet`]
/// via [`SourceSet::take_mem_table`] or [`SourceSet::take_table`].
pub fn get_db_table(&self) -> Option<&DbTable> {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can't see how rewrite this part...

crates/vm/src/lib.rs
//!
//! Run the AST build from [expr::Expr]. It assumes is correct.
//!

pub use spacetimedb_lib::operator;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our vm is not a vm anymore.

bfops
bfops approved these changes Mar 6, 2025
View reviewed changes
Copy link
Collaborator

@bfops bfops left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm approving the changes for my code-owned files:

crates/cli/src/config.rs
crates/cli/src/subcommands/subscribe.rs

I don't think I'm the right reviewer for the rest of these changes.

gefjon
gefjon requested changes Apr 3, 2025
View reviewed changes
Copy link
Contributor

@gefjon gefjon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't edit the generated module_bindings by hand; instead edit the templates in crates/cli/src/subcommands/generate/rust.rs .

@mamcx mamcx requested a review from jdetter as a code owner April 10, 2025 15:45
@jdetter
Copy link
Collaborator

jdetter commented Apr 11, 2025 •
edited
Loading

I don't have any input on this one, feel free to continue without me 👍

@mamcx mamcx force-pushed the mamcx/fix-docs-comments branch from ef6b60f to 18e4d03 Compare April 15, 2025 17:00
@mamcx @gefjon
Apply suggestions from code review
f197a64 
Co-authored-by: Phoebe Goldman <[email protected]>
Signed-off-by: Mario Montoya <[email protected]>
@mamcx mamcx force-pushed the mamcx/fix-docs-comments branch from 18e4d03 to f197a64 Compare April 15, 2025 18:15
@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@gefjon gefjon gefjon requested changes

@bfops bfops bfops approved these changes

@cloutiertyler cloutiertyler Awaiting requested review from cloutiertyler cloutiertyler is a code owner

@jdetter jdetter Awaiting requested review from jdetter jdetter is a code owner

Requested changes must be addressed to merge this pull request.

Assignees

@mamcx mamcx

Labels
documentation Improvements or additions to documentation release-any To be landed in any release window
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@mamcx @jdetter @CLAassistant @bfops @gefjon