From f9b71c8da0e511fbf6d88fe32908a11edf269ddc Mon Sep 17 00:00:00 2001 From: xmppftw Date: Sat, 16 Dec 2023 15:23:20 +0100 Subject: [PATCH] Improve documentation --- parsers/src/bookmarks.rs | 8 +++++--- parsers/src/bookmarks2.rs | 2 +- parsers/src/private.rs | 3 +++ 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/parsers/src/bookmarks.rs b/parsers/src/bookmarks.rs index 3a2c9a64..e32a20c4 100644 --- a/parsers/src/bookmarks.rs +++ b/parsers/src/bookmarks.rs @@ -5,14 +5,16 @@ // file, You can obtain one at http://mozilla.org/MPL/2.0/. //! -//! Chatroom bookmarks from [XEP-0048 v1.0](https://xmpp.org/extensions/attic/xep-0048-1.0.html). Only use on older servers -//! which do not advertise `urn:xmpp:bookmarks:1#compat` on the user's BareJID in a disco info request. -//! On modern compliant servers, use the [`crate::bookmarks2`] module instead. +//! Chatroom bookmarks from [XEP-0048](https://xmpp.org/extensions/attic/xep-0048-1.0.html). You should never use this, but use +//! [`bookmarks2`][`crate::bookmarks2`], or [`private::Query`][`crate::private::Query`] for legacy servers which do not advertise +//! `urn:xmpp:bookmarks:1#compat` on the user's BareJID in a disco info request. //! //! See [ModernXMPP docs](https://docs.modernxmpp.org/client/groupchat/#bookmarks) on how to handle all historic //! and newer specifications for your clients. //! //! This module exposes the [`Autojoin`][crate::bookmarks::Autojoin] boolean flag, the [`Conference`][crate::bookmarks::Conference] chatroom element, and the [`crate::ns::BOOKMARKS`] XML namespace. +//! +//! The [`Conference`][crate::bookmarks::Conference] struct used in [`private::Query`][`crate::private::Query`] is the one from this module. Only the querying mechanism changes from a legacy PubSub implementation here, to a legacy Private XML Query implementation in that other module. The [`Conference`][crate::bookmarks2::Conference] element from the [`bookmarks2`][crate::bookmarks2] module is a different structure, but conversion is possible from [`bookmarks::Conference`][crate::bookmarks::Conference] to [`bookmarks2::Conference`][crate::bookmarks2::Conference] via the [`Conference::into_bookmarks2`][crate::bookmarks::Conference::into_bookmarks2] method. use jid::BareJid; diff --git a/parsers/src/bookmarks2.rs b/parsers/src/bookmarks2.rs index 94551bc8..94951132 100644 --- a/parsers/src/bookmarks2.rs +++ b/parsers/src/bookmarks2.rs @@ -7,7 +7,7 @@ //! //! Chatroom bookmarks from [XEP-0402](https://xmpp.org/extensions/xep-0402.html) for newer servers //! which advertise `urn:xmpp:bookmarks:1#compat` on the user's BareJID in a disco info request. -//! On legacy non-compliant servers, use the [`crate::bookmarks`] module instead. +//! On legacy non-compliant servers, use the [`private`][crate::private] module instead. //! //! See [ModernXMPP docs](https://docs.modernxmpp.org/client/groupchat/#bookmarks) on how to handle all historic //! and newer specifications for your clients. diff --git a/parsers/src/private.rs b/parsers/src/private.rs index a0c6bc46..b1e91dcf 100644 --- a/parsers/src/private.rs +++ b/parsers/src/private.rs @@ -15,6 +15,9 @@ //! //! See [ModernXMPP docs](https://docs.modernxmpp.org/client/groupchat/#bookmarks) on how to handle //! all historic and newer specifications for your clients handling of chatroom bookmarks. +//! +//! This module uses the legacy bookmarks [`bookmarks::Conference`][crate::bookmarks::Conference] +//! struct as stored in a legacy [`bookmarks::Storage`][crate::bookmarks::Storage] struct. use crate::{ bookmarks::Storage,