Application documentation

atspi-proxies/src/accessible.rs

@@ -10,9 +10,16 @@ use crate::atspi_proxy;
 use crate::common::{InterfaceSet, ObjectRef, RelationType, Role, StateSet};
 use crate::AtspiError;
 
+/// # `AccessibleProxy`
+///
+/// A handle for a remote object implementing the `org.a11y.atspi.Accessible`
+/// interface.
+///
+/// Accessible is the interface which is implemented by all accessible objects.
+///
 #[atspi_proxy(interface = "org.a11y.atspi.Accessible", assume_defaults = true)]
 trait Accessible {
-	/// Returns an [`Accessible`] which refers to the `Application` object of the application.
+	/// Returns an [`ObjectRef`] which refers to the `Application` object of the application.
 	/// This object will have [`Application`] interface implemented.
 	///
 	/// The application object is the root of the accessibility hierarchy for the application.
@@ -23,8 +30,8 @@ trait Accessible {
 	/// guaranteed to be persistent for the lifetime of the application.
 	/// All other objects in the accessibility hierarchy may be created and destroyed dynamically.
 	///
-	/// [`Accessible`]: ../crate::common::events::Accessible
-	/// [`Application`]: <https://docs.rs/atspi-proxies/0.1.0/atspi_proxies/application/struct.ApplicationProxy.html>
+	/// [`ObjectRef`]: ../crate::common::events::ObjectRef
+	/// [`Application`]: crate::application::ApplicationProxy
 	fn get_application(&self) -> zbus::Result<ObjectRef>;
 
 	/// Gets a list of name/value pairs of attributes or annotations for this object.
@@ -33,8 +40,8 @@ trait Accessible {
 	/// For	typographic, textual, or textually-semantic attributes,
 	/// see [`TextProxy`]'s [`get_attributes`] method instead.
 	///
-	/// [`TextProxy`]: https://docs.rs/atspi-proxies/0.1.0/atspi_proxies/text/struct.TextProxy.html
-	/// [`get_attributes`]: https://docs.rs/atspi-proxies/0.1.0/atspi_proxies/text/struct.TextProxy.html#method.get_attributes
+	/// [`TextProxy`]: crate::text::TextProxy
+	/// [`get_attributes`]: crate::text::TextProxy#method.get_attributes
 	fn get_attributes(&self) -> zbus::Result<std::collections::HashMap<String, String>>;
 
 	/// Retrieve child by index (starting from 0),
@@ -59,10 +66,10 @@ trait Accessible {
 	///
 	/// ## Registry
 	///
-	/// On the `Accessible` interface of `org.a11y.atspi.Registry`, the registry daemon, this method retrieves a list
+	/// On the [`Accessible`] interface of `org.a11y.atspi.Registry`, the registry daemon, this method retrieves a list
 	/// of all accessible applications' root objects on the bus.
 	///
-	/// [`Accessible`]: ../crate::common::events::Accessible
+	/// [`Accessible`]: crate::accessible::AccessibleProxy
 	fn get_children(&self) -> zbus::Result<Vec<ObjectRef>>;
 
 	/// This object resides in its parent's list of children.

atspi-proxies/src/application.rs

@@ -1,39 +1,154 @@
-//! # `DBus` interface proxy for: `org.a11y.atspi.Application`
+//! # [`ApplicationProxy`]
 //!
-//! This code was generated by `zbus-xmlgen` `2.0.1` from `DBus` introspection data.
-//! Source: `Application.xml`.
+//! A handle for a remote object implementing the `org.a11y.atspi.Application`
+//! interface.
 //!
-//! You may prefer to adapt it, instead of using it verbatim.
+//! `Application` is the interface which is implemented by each accessible application.
+//! It is implemented for the root object of an application.
 //!
-//! More information can be found in the
-//! [Writing a client proxy](https://dbus.pages.freedesktop.org/zbus/client.html)
-//! section of the zbus documentation.
+//! It provides information about the application itself.
+//!
+//! ## Status
+//!
+//! A number of methods and properties of this interface have fallen in disuse or
+//! are / may be deprecated in the future.
+//!
+//! * [`id`]
+//! * [`set_id`]
+//! * [`atspi_version`]
+//! * [`get_locale`]
+//!  
+//! [`toolkit_name`] and [`version`] are still in use.
+//!
+//! See the documentation of the individual methods and properties for details.
+//!
+//! [`ApplicationProxy`]: crate::application::ApplicationProxy
+//! [`id`]: ApplicationProxy#method.id
+//! [`set_id`]: ApplicationProxy#method.set_id
+//! [`atspi_version`]: ApplicationProxy#method.atspi_version
+//! [`get_locale`]: ApplicationProxy#method.get_locale
+//! [`toolkit_name`]: ApplicationProxy#method.toolkit_name
+//! [`version`]: ApplicationProxy#method.version
 //!
 
 use crate::atspi_proxy;
 
+/// `Application` is the interface which is implemented by each accessible application.
+/// It is implemented for the root object of an application.
+///
+/// It provides information about the application itself.
+///
+/// ## Status
+///
+/// A number of methods and properties of this interface have fallen in disuse or
+/// are / may be deprecated in the future.
+///
+/// * [`id`]
+/// * [`set_id`]
+/// * [`atspi_version`]
+/// * [`get_locale`]
+///  
+/// [`toolkit_name`] and [`version`] are still in use.
+///
+/// See the documentation of the individual methods and properties for details.
+///
+/// [`id`]: ApplicationProxy#method.id
+/// [`set_id`]: ApplicationProxy#method.set_id
+/// [`atspi_version`]: ApplicationProxy#method.atspi_version
+/// [`get_locale`]: ApplicationProxy#method.get_locale
+/// [`toolkit_name`]: ApplicationProxy#method.toolkit_name
+/// [`version`]: ApplicationProxy#method.version
+///
 #[atspi_proxy(interface = "org.a11y.atspi.Application", assume_defaults = true)]
 trait Application {
-	/// GetLocale method
+	/// Method to retrieve the application's locale.
+	///
+	/// ## Deprecation
+	///  
+	/// This method is likely to be removed in the future.
+	///
+	/// There is no need to call this method because there is also
+	/// [`locale`] which offers the same functionality
+	/// at the accessible object level.
+	///
+	/// See also: [Orca issues: "Plans for per-object locale?"](<https://gitlab.gnome.org/GNOME/orca/-/issues/260>)
+	///
+	/// member: "GetLocale", type: method
+	///
+	/// [`locale`]: crate::accessible::AccessibleProxy#method.locale
 	fn get_locale(&self, lctype: u32) -> zbus::Result<String>;
 
-	/// AtspiVersion property
+	/// retrieves AT-SPI2 version.
+	///
+	/// Applications are advised to return "2.1" here, thus that is what
+	/// users should expect.
+	///
+	/// This was intended to be the version of the atspi interfaces
+	/// that the application supports, but atspi will probably move to
+	/// using versioned interface names instead.
+	///
+	/// member: "AtspiVersion", type: property
 	#[dbus_proxy(property)]
 	fn atspi_version(&self) -> zbus::Result<String>;
 
-	/// Id property
+	/// Retrieve numerical id of the application.
+	///
+	/// The 'id' is set an arbitrary numerical id when
+	/// an application registers with the registry.
+	///
+	/// When a freshly-started application uses the
+	/// [`org.a11y.atspi.Socket`]'s [`embed`] method to
+	/// register with the accessibility registry, the
+	/// registry will set a numerical id on the application.
+	///
+	/// ## status
+	///
+	/// The property has fallen in disuse.
+	///
+	/// As per [AT-SPI2-CORE issue #82](<https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues/82>)
+	/// it may turn out that this id is not actually used subsequently.
+	/// This is a remnant of the time when registryd actually had to
+	/// make up identifiers for each application.
+	/// With DBus, however,	it is the bus that assigns unique names to applications that
+	/// connect to it.
+	///
+	/// Applications or toolkits can remember the `Id` passed when the accessibility
+	/// registry sets this property, and return it back when the property is read.
+	///
+	/// member: "Id", type: property
+	///
+	/// [`embed`]: crate::socket::SocketProxy#method.embed
+	/// [`org.a11y.atspi.Socket`]: crate::socket::SocketProxy
 	#[dbus_proxy(property)]
 	fn id(&self) -> zbus::Result<i32>;
 
-	/// Set ID property
+	/// Set ID of the application.
+	///
+	/// This method is used by the accessibility registry to set the
+	/// application's id.
+	///
+	/// ## status
+	///
+	/// The property has fallen in disuse.
+	///
+	/// See [`id`] for details.
+	///
+	/// member: "Id", type: property
+	/// [`id`]: #method.id
 	#[dbus_proxy(property)]
 	fn set_id(&self, value: i32) -> zbus::Result<()>;
 
-	/// ToolkitName property
+	/// Retrieves the name of the toolkit used to implement the application's
+	/// user interface.
+	///
+	/// member: "ToolkitName", type: property
 	#[dbus_proxy(property)]
 	fn toolkit_name(&self) -> zbus::Result<String>;
 
-	/// Version property
+	/// Returns the version of the toolkit used to implement the
+	/// application's user interface.
+	///
+	/// member: "Version", type: property
 	#[dbus_proxy(property)]
 	fn version(&self) -> zbus::Result<String>;
 }