Add some basic docs to parts of the api

3 files changed, 80 insertions, 0 deletions

diff --git a/src/app.rs b/src/app.rs
index 169bbed..1a20caa 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -1,8 +1,10 @@
 use super::*;
 
+/// An id for a steam app/game
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct AppId(pub u32);
 
+/// Access to the steam apps interface
 pub struct Apps {
     pub(crate) apps: *mut sys::ISteamApps,
     pub(crate) _client: Arc<ClientInner>,
@@ -10,60 +12,83 @@ pub struct Apps {
 
 impl Apps {
 
+    /// Returns whether the user currently has the app with the given
+    /// ID currently installed.
+    ///
+    /// This does not mean the user owns the game.
     pub fn is_app_installed(&self, app_id: AppId) -> bool {
         unsafe {
             sys::SteamAPI_ISteamApps_BIsAppInstalled(self.apps, app_id.0) != 0
         }
     }
 
+    /// Returns whether the user owns the specific dlc and has it
+    /// installed.
     pub fn is_dlc_installed(&self, app_id: AppId) -> bool {
         unsafe {
             sys::SteamAPI_ISteamApps_BIsDlcInstalled(self.apps, app_id.0) != 0
         }
     }
 
+    /// Returns whether the user is subscribed to the app with the given
+    /// ID.
+    ///
+    /// This should only be used to check ownership of a game related to
+    /// yours (e.g. demo).
     pub fn is_subscribed_app(&self, app_id: AppId) -> bool {
         unsafe {
             sys::SteamAPI_ISteamApps_BIsSubscribedApp(self.apps, app_id.0) != 0
         }
     }
 
+    /// Returns whether the user is subscribed via a free weekend
     pub fn is_subscribed_from_free_weekend(&self) -> bool {
         unsafe {
             sys::SteamAPI_ISteamApps_BIsSubscribedFromFreeWeekend(self.apps) != 0
         }
     }
 
+    /// Returns whether the user has a VAC ban on their account.
     pub fn is_vac_banned(&self) -> bool {
         unsafe {
             sys::SteamAPI_ISteamApps_BIsVACBanned(self.apps) != 0
         }
     }
 
+    /// Returns whether the license for the current app ID
+    /// is for cyber cafes.
     pub fn is_cybercafe(&self) -> bool {
         unsafe {
             sys::SteamAPI_ISteamApps_BIsCybercafe(self.apps) != 0
         }
     }
 
+    /// Returns whether the license for the current app ID
+    /// provides low violence depots.
     pub fn is_low_violence(&self) -> bool {
         unsafe {
             sys::SteamAPI_ISteamApps_BIsLowViolence(self.apps) != 0
         }
     }
 
+    /// Returns whether the user is subscribed to the current app ID
     pub fn is_subscribed(&self) -> bool {
         unsafe {
             sys::SteamAPI_ISteamApps_BIsSubscribed(self.apps) != 0
         }
     }
 
+    /// Returns the buildid of this app.
     pub fn app_build_id(&self) -> i32 {
         unsafe {
             sys::SteamAPI_ISteamApps_GetAppBuildId(self.apps) as i32
         }
     }
 
+    /// Returns the installation folder of the app with the given ID.
+    ///
+    /// This works even if the app isn't installed, returning where it
+    /// would be installed in the default location.
     pub fn app_install_dir(&self, app_id: AppId) -> String {
         unsafe {
             let buffer = vec![0; 2048];
@@ -73,12 +98,16 @@ impl Apps {
         }
     }
 
+    /// Returns the steam id of the original owner of the app.
+    ///
+    /// Differs from the current user if the app is borrowed.
     pub fn app_owner(&self) -> SteamId {
         unsafe {
             SteamId(sys::SteamAPI_ISteamApps_GetAppOwner(self.apps))
         }
     }
 
+    /// Returns a list of languages that the current app supports.
     pub fn available_game_languages(&self) -> Vec<String> {
         unsafe {
             let langs = sys::SteamAPI_ISteamApps_GetAvailableGameLanguages(self.apps);
@@ -90,6 +119,10 @@ impl Apps {
         }
     }
 
+    /// Returns the language the user has set for the current game.
+    ///
+    /// If the language hasn't been set this returns the language
+    /// used for the steam UI.
     pub fn current_game_language(&self) -> Cow<str> {
         unsafe {
             let lang = sys::SteamAPI_ISteamApps_GetCurrentGameLanguage(self.apps);
@@ -98,6 +131,10 @@ impl Apps {
         }
     }
 
+    /// Returns the current beta name if any.
+    ///
+    /// If the user isn't playing on a beta branch then this
+    /// returns `None`
     pub fn current_beta_name(&self) -> Option<String> {
         unsafe {
             let buffer = vec![0; 256];
diff --git a/src/lib.rs b/src/lib.rs
index 9805426..e76361e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -30,6 +30,10 @@ use std::fmt::{
 // however this is never stated anywhere in the docs
 // that I could see.
 
+/// The main entry point into the steam client.
+///
+/// This provides access to all of the steamworks api.
+#[derive(Clone)]
 pub struct Client {
     inner: Arc<ClientInner>,
 }
@@ -42,6 +46,23 @@ struct ClientInner {
 }
 
 impl Client {
+    /// Attempts to initialize the steamworks api and returns
+    /// a client to access the rest of the api.
+    ///
+    /// This should only ever have one instance per a program.
+    ///
+    /// # Errors
+    ///
+    /// This can fail if:
+    /// * The steam client isn't running
+    /// * The app ID of the game couldn't be determined.
+    ///
+    ///   If the game isn't being run through steam this can be provided by
+    ///   placing a `steam_appid.txt` with the ID inside in the current
+    ///   working directory
+    /// * The game isn't running on the same user/level as the steam client
+    /// * The user doesn't own a license for the game.
+    /// * The app ID isn't completely set up.
     pub fn init() -> SResult<Client> {
         unsafe {
             if sys::SteamAPI_Init() == 0 {
@@ -59,12 +80,24 @@ impl Client {
         }
     }
 
+    /// Runs any currently pending callbacks
+    ///
+    /// This runs all currently pending callbacks on the current
+    /// thread.
+    ///
+    /// This should be called frequently (e.g. once per a frame)
+    /// in order to reduce the latency between recieving events.
     pub fn run_callbacks(&self) {
         unsafe {
             sys::SteamAPI_RunCallbacks();
         }
     }
 
+    /// Registers the passed function as a callback for the
+    /// given type.
+    ///
+    /// The callback will be run on the thread that `run_callbacks`
+    /// is called when the event arrives.
     pub fn register_callback<C, F>(&self, f: F)
         where C: Callback,
               F: FnMut(C) + 'static + Send + Sync
@@ -102,6 +135,7 @@ impl Client {
         }
     }
 
+    /// Returns an accessor to the steam utils interface
     pub fn utils(&self) -> Utils {
         unsafe {
             let utils = sys::SteamAPI_ISteamClient_GetISteamUtils(
@@ -116,6 +150,7 @@ impl Client {
         }
     }
 
+    /// Returns an accessor to the steam apps interface
     pub fn apps(&self) -> Apps {
         unsafe {
             let user = sys::SteamAPI_ISteamClient_ConnectToGlobalUser(self.inner.client, self.inner.pipe);
@@ -131,6 +166,7 @@ impl Client {
         }
     }
 
+    /// Returns an accessor to the steam friends interface
     pub fn friends(&self) -> Friends {
         unsafe {
             let user = sys::SteamAPI_ISteamClient_ConnectToGlobalUser(self.inner.client, self.inner.pipe);
@@ -160,6 +196,7 @@ impl Drop for ClientInner {
     }
 }
 
+/// A user's steam id
 #[derive(Clone, Copy, Debug)]
 pub struct SteamId(pub(crate) u64);
 
diff --git a/src/utils.rs b/src/utils.rs
index f95719f..2ad34f1 100644
--- a/src/utils.rs
+++ b/src/utils.rs
@@ -1,18 +1,24 @@
 
 use super::*;
 
+/// Access to the steam utils interface
 pub struct Utils {
     pub(crate) utils: *mut sys::ISteamUtils,
     pub(crate) _client: Arc<ClientInner>,
 }
 
 impl Utils {
+    /// Returns the app ID of the current process
     pub fn app_id(&self) -> AppId {
         unsafe {
             AppId(sys::SteamAPI_ISteamUtils_GetAppID(self.utils))
         }
     }
 
+    /// Returns the language the steam client is currently
+    /// running in.
+    ///
+    /// Generally you want `Apps::current_game_language` instead of this
     pub fn ui_language(&self) -> Cow<str> {
         unsafe {
             let lang = sys::SteamAPI_ISteamUtils_GetSteamUILanguage(self.utils);