From cd7a2de329e31344bde73981ebb8417448bd8033 Mon Sep 17 00:00:00 2001 From: Heath Stewart Date: Sat, 17 Feb 2024 12:33:13 -0800 Subject: [PATCH] Update documentation (#31) --- .github/workflows/ci.yml | 2 +- .github/workflows/release.yml | 2 +- Cargo.toml | 2 +- LICENSE.txt | 2 +- README.md | 2 +- examples/deferred/deferred.wxs | 2 +- examples/deferred/lib.rs | 2 +- examples/example.wxs | 2 +- examples/skip/lib.rs | 2 +- examples/skip/skip.wxs | 2 +- src/database.rs | 2 +- src/error.rs | 2 +- src/error/experimental.rs | 4 ++-- src/ffi.rs | 2 +- src/lib.rs | 2 +- src/record.rs | 2 +- src/session.rs | 6 +++--- src/view.rs | 26 ++++++++++++++------------ 18 files changed, 34 insertions(+), 32 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8e0d2bd..cd36c72 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,4 +1,4 @@ -# Copyright 2022 Heath Stewart. +# Copyright 2024 Heath Stewart. # Licensed under the MIT License. See LICENSE.txt in the project root for license information. name: ci diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 687efe0..7d41496 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,4 +1,4 @@ -# Copyright 2022 Heath Stewart. +# Copyright 2024 Heath Stewart. # Licensed under the MIT License. See LICENSE.txt in the project root for license information. name: release diff --git a/Cargo.toml b/Cargo.toml index 5f3a19a..434b26c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,4 +1,4 @@ -# Copyright 2022 Heath Stewart. +# Copyright 2024 Heath Stewart. # Licensed under the MIT License. See LICENSE.txt in the project root for license information. [package] diff --git a/LICENSE.txt b/LICENSE.txt index fbb12b1..d2bdadb 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,4 +1,4 @@ -Copyright 2022 Heath Stewart +Copyright 2024 Heath Stewart Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: diff --git a/README.md b/README.md index b62d874..ae45109 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ pub extern "C" fn MyCustomAction(session: Session) -> CustomActionResult { ## License -This project is licensed under the [MIT license](LICENSE.txt). +This project is licensed under the [MIT license](https://github.com/heaths/msica-rs/blob/main/LICENSE.txt). [automation interface]: https://docs.microsoft.com/windows/win32/msi/automation-interface [custom actions]: https://docs.microsoft.com/windows/win32/msi/custom-actions diff --git a/examples/deferred/deferred.wxs b/examples/deferred/deferred.wxs index 62b5491..1ce6989 100644 --- a/examples/deferred/deferred.wxs +++ b/examples/deferred/deferred.wxs @@ -1,6 +1,6 @@ diff --git a/examples/deferred/lib.rs b/examples/deferred/lib.rs index f0e66f0..fe679b8 100644 --- a/examples/deferred/lib.rs +++ b/examples/deferred/lib.rs @@ -1,4 +1,4 @@ -// Copyright 2022 Heath Stewart. +// Copyright 2024 Heath Stewart. // Licensed under the MIT License. See LICENSE.txt in the project root for license information. use msica::prelude::*; diff --git a/examples/example.wxs b/examples/example.wxs index 7c0d9a9..c814616 100644 --- a/examples/example.wxs +++ b/examples/example.wxs @@ -1,6 +1,6 @@ diff --git a/examples/skip/lib.rs b/examples/skip/lib.rs index 7d84626..c2766e2 100644 --- a/examples/skip/lib.rs +++ b/examples/skip/lib.rs @@ -1,4 +1,4 @@ -// Copyright 2022 Heath Stewart. +// Copyright 2024 Heath Stewart. // Licensed under the MIT License. See LICENSE.txt in the project root for license information. use msica::prelude::*; diff --git a/examples/skip/skip.wxs b/examples/skip/skip.wxs index cf09438..fb692c0 100644 --- a/examples/skip/skip.wxs +++ b/examples/skip/skip.wxs @@ -1,6 +1,6 @@ diff --git a/src/database.rs b/src/database.rs index f83b38a..0d32222 100644 --- a/src/database.rs +++ b/src/database.rs @@ -1,4 +1,4 @@ -// Copyright 2022 Heath Stewart. +// Copyright 2024 Heath Stewart. // Licensed under the MIT License. See LICENSE.txt in the project root for license information. use crate::ffi; diff --git a/src/error.rs b/src/error.rs index b90a6b1..f55b96b 100644 --- a/src/error.rs +++ b/src/error.rs @@ -1,4 +1,4 @@ -// Copyright 2022 Heath Stewart. +// Copyright 2024 Heath Stewart. // Licensed under the MIT License. See LICENSE.txt in the project root for license information. use crate::Record; diff --git a/src/error/experimental.rs b/src/error/experimental.rs index 87ab079..9b28e0e 100644 --- a/src/error/experimental.rs +++ b/src/error/experimental.rs @@ -1,4 +1,4 @@ -// Copyright 2022 Heath Stewart. +// Copyright 2024 Heath Stewart. // Licensed under the MIT License. See LICENSE.txt in the project root for license information. #![cfg(feature = "nightly")] @@ -11,7 +11,7 @@ use std::ops::{ControlFlow, FromResidual, Try}; /// A result to return from a custom action. /// -/// This allows you to use the `?` operator to map any `Result` to [`CustomActionResult::Fail`]. +/// This allows you to use the `?` operator to map any `Result` to [`CustomActionResult::Failure`]. /// /// # Example /// diff --git a/src/ffi.rs b/src/ffi.rs index 1a9f66e..e0dbd88 100644 --- a/src/ffi.rs +++ b/src/ffi.rs @@ -1,4 +1,4 @@ -// Copyright 2022 Heath Stewart. +// Copyright 2024 Heath Stewart. // Licensed under the MIT License. See LICENSE.txt in the project root for license information. #![allow(clippy::upper_case_acronyms)] diff --git a/src/lib.rs b/src/lib.rs index fe4c902..6d0ba20 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,4 +1,4 @@ -// Copyright 2022 Heath Stewart. +// Copyright 2024 Heath Stewart. // Licensed under the MIT License. See LICENSE.txt in the project root for license information. #![allow(dead_code)] diff --git a/src/record.rs b/src/record.rs index c20e348..437d2d6 100644 --- a/src/record.rs +++ b/src/record.rs @@ -1,4 +1,4 @@ -// Copyright 2022 Heath Stewart. +// Copyright 2024 Heath Stewart. // Licensed under the MIT License. See LICENSE.txt in the project root for license information. use crate::ffi; diff --git a/src/session.rs b/src/session.rs index 589d52b..125615b 100644 --- a/src/session.rs +++ b/src/session.rs @@ -1,4 +1,4 @@ -// Copyright 2022 Heath Stewart. +// Copyright 2024 Heath Stewart. // Licensed under the MIT License. See LICENSE.txt in the project root for license information. use crate::ffi; @@ -41,7 +41,7 @@ impl Session { /// If `None` the default action is run e.g., `INSTALL`. /// /// To schedule a deferred custom action with its `CustomActionData`, - /// call `do_deferred_action`. + /// call [`Session::do_deferred_action()`]. pub fn do_action(&self, action: Option<&str>) -> Result<()> { unsafe { let action = match action { @@ -195,7 +195,7 @@ pub enum MessageType { CommonData = 0x0b00_0000, } -/// Run modes passed to `Session::mode`. +/// Run modes passed to [`Session::mode()`]. #[repr(u32)] pub enum RunMode { /// Administrative mode install, else product install. diff --git a/src/view.rs b/src/view.rs index 26ef2af..dbfea12 100644 --- a/src/view.rs +++ b/src/view.rs @@ -1,4 +1,4 @@ -// Copyright 2022 Heath Stewart. +// Copyright 2024 Heath Stewart. // Licensed under the MIT License. See LICENSE.txt in the project root for license information. use crate::ffi; @@ -8,12 +8,12 @@ use crate::{Error, Record, Result}; use crate::Database; /// The `View` object represents a result set obtained when processing a query -/// using the `OpenView` method of the [`Database`] object. Before any data can be transferred, -/// the query must be executed using the `execute` method, passing to it all replaceable parameters +/// using the [`Database::open_view()`] method. Before any data can be transferred, +/// the query must be executed using the [`View::execute()`] method, passing to it all replaceable parameters /// designated within the SQL query string. /// /// The query may be executed again, with different parameters if needed, -/// but only after freeing the result set either by fetching all the records or by calling the `close` method. +/// but only after freeing the result set either by fetching all the records or by calling the [`View::close()`] method. pub struct View { h: ffi::PMSIHANDLE, } @@ -21,7 +21,7 @@ pub struct View { impl View { /// Releases the result set for an executed view. /// - /// `close` must be called before `execute` can be called again unless all records have been fetched. + /// `close` must be called before [`View::execute()`] can be called again unless all records have been fetched. pub fn close(&self) { unsafe { ffi::MsiViewClose(*self.h); @@ -33,7 +33,7 @@ impl View { /// /// The values of these parameters are passed in as the corresponding fields of a parameter record. /// - /// `close` must be called before `execute` can be called again unless all records have been fetched. + /// [`View::close()`] must be called before `execute` can be called again unless all records have been fetched. pub fn execute(&self, record: Option) -> Result<()> { unsafe { let h = match record { @@ -54,7 +54,9 @@ impl View { /// Updates a fetched record. /// - /// You can pass `Update` or `Delete` with a record immediately after using `Insert`, `InsertTemporary`, or `Seek` provided you have *not* modified the 0th field of the inserted or sought record. + /// You can pass [`Update`](ModifyMode::Update) or [`Delete`](ModifyMode::Delete) with a record immediately after using + /// [`Insert`](ModifyMode::Insert), [`InsertTemporary`](ModifyMode::InsertTemporary), or [`Seek`](ModifyMode::Seek) + /// provided you have *not* modified the 0th field of the inserted or sought record. /// /// You cannot fetch a record that contains binary data from one database and then use that record to insert the data into another database. /// @@ -101,7 +103,7 @@ impl Iterator for View { } } -/// Modify modes passed to `View::modify`. +/// Modify modes passed to [`View::modify()`]. #[repr(u32)] pub enum ModifyMode { /// Refreshes the information in the supplied record without changing the position in the result set and without affecting subsequent fetch operations. @@ -109,7 +111,7 @@ pub enum ModifyMode { /// Seek cannot be used with multi-table queries. This mode cannot be used with a view containing joins. Seek = u32::MAX, - /// Refreshes the information in the record. Must first call `fetch` on [`View`] with the same record. + /// Refreshes the information in the record. Must first call [`View::next()`] with the same record. /// Fails for a deleted row. Works with read-write and read-only records. Refresh = 0, @@ -117,7 +119,7 @@ pub enum ModifyMode { /// This mode cannot be used with a view containing joins. Insert = 1, - /// Updates an existing record. Non-primary keys only. Must first call `fetch` on [`View`]. + /// Updates an existing record. Non-primary keys only. Must first call [`View::next()`]. /// Fails with a deleted record. Works only with read-write records. Update = 2, @@ -125,7 +127,7 @@ pub enum ModifyMode { /// Fails with a read-only database. This mode cannot be used with a view containing joins. Assign = 3, - /// Updates or deletes and inserts a record into a table. Must first call `fetch` on [`View`] with the same record. + /// Updates or deletes and inserts a record into a table. Must first call [`View::next()`] with the same record. /// Updates record if the primary keys are unchanged. Deletes old row and inserts new if primary keys have changed. Fails with a read-only database. /// This mode cannot be used with a view containing joins. Replace = 4, @@ -135,7 +137,7 @@ pub enum ModifyMode { /// This mode cannot be used with a view containing joins. Merge = 5, - /// Remove a row from the table. You must first call the `fetch` on [`View`] function with the same record. + /// Remove a row from the table. You must first call the [`View::next()`] function with the same record. /// Fails if the row has been deleted. Works only with read-write records. This mode cannot be used with a view containing joins. Delete = 6,