From ba083ada7dfa09215729c3f937c1491d56ca54cb Mon Sep 17 00:00:00 2001 From: Emil Ernerfeldt Date: Mon, 25 Mar 2024 18:20:06 +0100 Subject: [PATCH] Standardize the doc tags --- .../definitions/rerun/archetypes/image.fbs | 6 ++-- .../definitions/rerun/archetypes/points2d.fbs | 4 +-- .../definitions/rerun/archetypes/points3d.fbs | 4 +-- .../re_types_builder/src/codegen/cpp/mod.rs | 2 +- .../re_types_builder/src/codegen/docs/mod.rs | 2 +- .../src/codegen/python/mod.rs | 8 ++--- .../re_types_builder/src/codegen/rust/api.rs | 2 +- crates/re_types_builder/src/docs.rs | 32 ++++++++++++------- 8 files changed, 34 insertions(+), 26 deletions(-) diff --git a/crates/re_types/definitions/rerun/archetypes/image.fbs b/crates/re_types/definitions/rerun/archetypes/image.fbs index db69aee740b1..3d9ab91b2126 100644 --- a/crates/re_types/definitions/rerun/archetypes/image.fbs +++ b/crates/re_types/definitions/rerun/archetypes/image.fbs @@ -18,9 +18,9 @@ namespace rerun.archetypes; /// /// Rerun also supports compressed image encoded as JPEG, N12, and YUY2. /// Using these formats can save a lot of bandwidth and memory. -/// \python To compress an image, use [`rerun.Image.compress`][]. -/// \python To pass in an already encoded image, use [`rerun.ImageEncoded`][]. -/// \rust See [`crate::components::TensorData`] for more. +/// \py To compress an image, use [`rerun.Image.compress`][]. +/// \py To pass in an already encoded image, use [`rerun.ImageEncoded`][]. +/// \rs See [`crate::components::TensorData`] for more. /// \cpp See [`rerun::datatypes::TensorBuffer`] for more. /// /// \cpp Since the underlying `rerun::datatypes::TensorData` uses `rerun::Collection` internally, diff --git a/crates/re_types/definitions/rerun/archetypes/points2d.fbs b/crates/re_types/definitions/rerun/archetypes/points2d.fbs index 7e4f70d4fb94..fdc48f20edf9 100644 --- a/crates/re_types/definitions/rerun/archetypes/points2d.fbs +++ b/crates/re_types/definitions/rerun/archetypes/points2d.fbs @@ -28,8 +28,8 @@ table Points2D ( /// Optional colors for the points. /// - /// \python The colors are interpreted as RGB or RGBA in sRGB gamma-space, - /// \python As either 0-1 floats or 0-255 integers, with separate alpha. + /// \py The colors are interpreted as RGB or RGBA in sRGB gamma-space, + /// \py As either 0-1 floats or 0-255 integers, with separate alpha. colors: [rerun.components.Color] ("attr.rerun.component_recommended", nullable, order: 2100); // --- Optional --- diff --git a/crates/re_types/definitions/rerun/archetypes/points3d.fbs b/crates/re_types/definitions/rerun/archetypes/points3d.fbs index aa109118fe3d..f569f0caabec 100644 --- a/crates/re_types/definitions/rerun/archetypes/points3d.fbs +++ b/crates/re_types/definitions/rerun/archetypes/points3d.fbs @@ -26,8 +26,8 @@ table Points3D ( /// Optional colors for the points. /// - /// \python The colors are interpreted as RGB or RGBA in sRGB gamma-space, - /// \python As either 0-1 floats or 0-255 integers, with separate alpha. + /// \py The colors are interpreted as RGB or RGBA in sRGB gamma-space, + /// \py As either 0-1 floats or 0-255 integers, with separate alpha. colors: [rerun.components.Color] ("attr.rerun.component_recommended", nullable, order: 2100); // --- Optional --- diff --git a/crates/re_types_builder/src/codegen/cpp/mod.rs b/crates/re_types_builder/src/codegen/cpp/mod.rs index b24dc8151c0e..1c48d66edfb3 100644 --- a/crates/re_types_builder/src/codegen/cpp/mod.rs +++ b/crates/re_types_builder/src/codegen/cpp/mod.rs @@ -2265,7 +2265,7 @@ fn quote_field_docs(field: &ObjectField) -> TokenStream { } fn lines_from_docs(docs: &Docs) -> Vec { - let mut lines = docs.doc_lines_for_untagged_and(&["cpp", "c++"]); + let mut lines = docs.doc_lines_for_untagged_and("cpp"); let required = true; let examples = collect_snippets_for_api_docs(docs, "cpp", required).unwrap_or_default(); diff --git a/crates/re_types_builder/src/codegen/docs/mod.rs b/crates/re_types_builder/src/codegen/docs/mod.rs index 6e21a4e5ac5c..119c48fb76c7 100644 --- a/crates/re_types_builder/src/codegen/docs/mod.rs +++ b/crates/re_types_builder/src/codegen/docs/mod.rs @@ -141,7 +141,7 @@ fn index_page(kind: ObjectKind, order: u64, prelude: &str, objects: &[&Object]) fn object_page(reporter: &Reporter, object: &Object, object_map: &ObjectMap) -> String { let is_unreleased = object.is_attr_set(crate::ATTR_DOCS_UNRELEASED); - let top_level_docs = object.docs.doc_lines_for_untagged_and(&[]); + let top_level_docs = object.docs.untagged(); if top_level_docs.is_empty() { reporter.error(&object.virtpath, &object.fqname, "Undocumented object"); diff --git a/crates/re_types_builder/src/codegen/python/mod.rs b/crates/re_types_builder/src/codegen/python/mod.rs index ae1636c17951..f41c57804000 100644 --- a/crates/re_types_builder/src/codegen/python/mod.rs +++ b/crates/re_types_builder/src/codegen/python/mod.rs @@ -1157,7 +1157,7 @@ fn quote_obj_docs(obj: &Object) -> String { } fn lines_from_docs(docs: &Docs) -> Vec { - let mut lines = docs.doc_lines_for_untagged_and(&["py", "python"]); + let mut lines = docs.doc_lines_for_untagged_and("py"); let examples = collect_snippets_for_api_docs(docs, "py", true).unwrap(); if !examples.is_empty() { @@ -1208,7 +1208,7 @@ fn quote_doc_from_fields(objects: &Objects, fields: &Vec) -> String let mut lines = vec!["Must be one of:".to_owned(), String::new()]; for field in fields { - let mut content = field.docs.doc_lines_for_untagged_and(&["py", "python"]); + let mut content = field.docs.doc_lines_for_untagged_and("py"); for line in &mut content { if line.starts_with(char::is_whitespace) { line.remove(0); @@ -1250,7 +1250,7 @@ fn quote_union_kind_from_fields(fields: &Vec) -> String { let mut lines = vec!["Possible values:".to_owned(), String::new()]; for field in fields { - let mut content = field.docs.doc_lines_for_untagged_and(&["py", "python"]); + let mut content = field.docs.doc_lines_for_untagged_and("py"); for line in &mut content { if line.starts_with(char::is_whitespace) { line.remove(0); @@ -1950,7 +1950,7 @@ fn quote_init_method( obj.fields .iter() .filter_map(|field| { - let doc_content = field.docs.doc_lines_for_untagged_and(&["py", "python"]); + let doc_content = field.docs.doc_lines_for_untagged_and("py"); if doc_content.is_empty() { if !field.is_testing() && obj.fields.len() > 1 { reporter.error( diff --git a/crates/re_types_builder/src/codegen/rust/api.rs b/crates/re_types_builder/src/codegen/rust/api.rs index 2ea9a73e912f..a89613137681 100644 --- a/crates/re_types_builder/src/codegen/rust/api.rs +++ b/crates/re_types_builder/src/codegen/rust/api.rs @@ -714,7 +714,7 @@ fn quote_obj_docs(reporter: &Reporter, obj: &Object) -> TokenStream { } fn doc_as_lines(reporter: &Reporter, virtpath: &str, fqname: &str, docs: &Docs) -> Vec { - let mut lines = docs.doc_lines_for_untagged_and(&["rs", "rust"]); + let mut lines = docs.doc_lines_for_untagged_and("rs"); let examples = collect_snippets_for_api_docs(docs, "rs", true) .map_err(|err| reporter.error(virtpath, fqname, err)) diff --git a/crates/re_types_builder/src/docs.rs b/crates/re_types_builder/src/docs.rs index e7723e724cb1..c56077350ad2 100644 --- a/crates/re_types_builder/src/docs.rs +++ b/crates/re_types_builder/src/docs.rs @@ -125,6 +125,11 @@ impl Docs { let mut tagged_docs = BTreeMap::new(); for cur_tag in all_tags { + assert!( + matches!(cur_tag.as_str(), "example" | "py" | "rs" | "cpp"), + "Unsupported tag: \\{cur_tag}" + ); + tagged_docs.insert( cur_tag.clone(), tagged_lines @@ -152,21 +157,24 @@ impl Docs { } } - /// Get all doc lines that are untagged, or match any of the given tags. + /// Get all doc lines that are untagged. + pub fn untagged(&self) -> Vec { + self.doc_lines_for_untagged_and("") + } + + /// Get all doc lines that are untagged, or match the given tag. /// - /// For instance, pass `["py"]` to get all lines that are untagged or starta with `"\python"`. - pub fn doc_lines_for_untagged_and(&self, tags: &[&str]) -> Vec { + /// For instance, pass `"py"` to get all lines that are untagged or starta with `"\py"`. + pub fn doc_lines_for_untagged_and(&self, tag: &str) -> Vec { let mut lines = self.doc.clone(); - for tag in tags { - lines.extend( - self.tagged_docs - .get(*tag) - .unwrap_or(&Vec::new()) - .iter() - .cloned(), - ); - } + lines.extend( + self.tagged_docs + .get(tag) + .unwrap_or(&Vec::new()) + .iter() + .cloned(), + ); // NOTE: remove duplicated blank lines. lines.dedup();