From 9fa1ee8cf62adac1e046e8b7ece25f95f8d4c04f Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Fri, 3 Mar 2023 04:14:32 +0100 Subject: [PATCH] Doc(Addentum) - Adds more documentation --- src/bin/xiv_csolver.rs | 54 ++++++++++++++++++++++++++++++++------- src/lib.rs | 58 ++++++++++++++++++++++++++++++++++-------- 2 files changed, 92 insertions(+), 20 deletions(-) diff --git a/src/bin/xiv_csolver.rs b/src/bin/xiv_csolver.rs index 8377794..c94c690 100644 --- a/src/bin/xiv_csolver.rs +++ b/src/bin/xiv_csolver.rs @@ -5,13 +5,14 @@ //! //! This project also provides bindings for python to allow hooking it to any form of better GUI/CLI //! -//! The project is (for now) self hosted and hosted on [Github](https://github.com/Dandaedre/xiv_csolver) +//! The project is (for now) self-hosted and hosted on [Github](https://github.com/Dandaedre/xiv_csolver) //! //! ## Getting started //! -//! ### Developpement +//! ### Development //! -//! To setup the whole developpement environement it is recommended to use cargo-make +//! #### Rust +//! To set up the whole development environment, it is recommended to use cargo-make //! //! Doing so will allow you custom commands to //! @@ -23,16 +24,19 @@ //! ```sh //! cargo make release //! ``` -//! To generate the release files, bins and libs, pakage them and make them ready to release +//! To generate the release files, bins and libs, package them and make them ready to release //! +//! #### Python //! -//! It is really recommanded to setup a venv to handle the python developpement +//! It is really recommended to set up a venv to handle the python development +//! +//! All bindings and the explanation of how to use them can be found in the [`io`](crate::io) module. //! //! ### Features //! //! Use these by running `cargo run/build --features ` //! -//! - ``no_python`` : Dont build the lib & python bindings (WIP, not fully implemented) +//! - ``no_python`` : Don't build the lib & python bindings (WIP, not fully implemented) //! - ``fast`` : Don't allow some under-optimisation to run (saving global run-time) //! - ``verbose`` : Allow for more debug messages (note that -v(vv) must still be passed to activate them) //! @@ -44,17 +48,49 @@ //! cargo install maturin //! maturin develop //! ``` +//! ## Solving and bias +//! +//! The solving algorithm used has a very strong bias toward a particular method: +//! +//! - **Step 1** : Try to push the progression of the craft one step before being finishable +//! - **Step 2** : Try to increase the quality as much as possible. +//! - **Step 3** : Finish the craft +//! +//! To account for a lot of possibilities, step one generates all methods to try and finish the craft +//! and step two tests all methods to up the quality until all crafting points are depleted +//! Doing so ensures by brute force that all permutations are thoroughly tested. +//! +//! While this method works and is very likely the best method for the current patch, +//! a rework of the crafting actions could very well make this method subpar or at least +//! on par with another method. +//! +//! In layman's term, only the groundwork opening is tested and no delicate synthesis spam is tested. +//! However, for now, these two crafting techniques remain subpar and discarding them comes at no +//! loss for the crafter. +//! +//! Others algorithm exists and could very well cover all other basis at the expense of runtime. +//! We have chosen not to implement them as they (for now) would be very unlikely to uncover anything +//! meaningful. +//! +//! ### Leveling +//! +//! We have (for now at least) no intention to release a leveling feature to the crafting solver +//! However, selecting some spells and buffs and have them disabled could be added as a feature +//! hence making a "leveling" option +//! +//! If it is ever released, this feature is likely to be heavily reliant on the python GUI. +//! //! //! ## Contributing //! //! All form of contributions are welcome ! //! -//! While this project was originnaly a collab and didn't strive to encompass every need +//! While this project was originally a collab and didn't strive to encompass every need //! of a modern FFXIV crafter, more polish and finish is always welcome. //! -//! ## Licence +//! ## License //! -//! The original code was released without a licence by [RikaKagurasaka](https://github.com/RikaKagurasaka/xiv_craft_solver) +//! The original code was released without a license by [RikaKagurasaka](https://github.com/RikaKagurasaka/xiv_craft_solver) //! //! All this fork's code is released under [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0) diff --git a/src/lib.rs b/src/lib.rs index f8a36fe..96c4de4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,13 +5,14 @@ //! //! This project also provides bindings for python to allow hooking it to any form of better GUI/CLI //! -//! The project is (for now) self hosted and hosted on [Github](https://github.com/Dandaedre/xiv_csolver) +//! The project is (for now) self-hosted and hosted on [Github](https://github.com/Dandaedre/xiv_csolver) //! //! ## Getting started //! -//! ### Developpement +//! ### Development //! -//! To setup the whole developpement environement it is recommended to use cargo-make +//! #### Rust +//! To set up the whole development environment, it is recommended to use cargo-make //! //! Doing so will allow you custom commands to //! @@ -23,18 +24,21 @@ //! ```sh //! cargo make release //! ``` -//! To generate the release files, bins and libs, pakage them and make them ready to release +//! To generate the release files, bins and libs, package them and make them ready to release //! +//! #### Python //! -//! It is really recommanded to setup a venv to handle the python developpement +//! It is really recommended to set up a venv to handle the python development +//! +//! All bindings and the explanation of how to use them can be found in the [`io`](crate::io) module. //! //! ### Features //! //! Use these by running `cargo run/build --features ` //! -//! - ``no_python`` : Dont build the lib & python bindings (WIP, not fully implemented) -//! - ``fast``: Don't allow some under-optimisation to run (saving global run-time) -//! - ``verbose`` : Allow for more debug messages (note that -v(vv) must still be passed to activate them) +//! - ``no_python`` : Don't build the lib & python bindings (WIP, not fully implemented) +//! - ``fast`` : Don't allow some under-optimisation to run (saving global run-time) +//! - ``verbose`` : Allow for more debug messages (note that -v(vv) must still be passed to activate them) //! //! ## Regenerating the API Bindings //! @@ -44,17 +48,49 @@ //! cargo install maturin //! maturin develop //! ``` +//! ## Solving and bias +//! +//! The solving algorithm used has a very strong bias toward a particular method: +//! +//! - **Step 1** : Try to push the progression of the craft one step before being finishable +//! - **Step 2** : Try to increase the quality as much as possible. +//! - **Step 3** : Finish the craft +//! +//! To account for a lot of possibilities, step one generates all methods to try and finish the craft +//! and step two tests all methods to up the quality until all crafting points are depleted +//! Doing so ensures by brute force that all permutations are thoroughly tested. +//! +//! While this method works and is very likely the best method for the current patch, +//! a rework of the crafting actions could very well make this method subpar or at least +//! on par with another method. +//! +//! In layman's term, only the groundwork opening is tested and no delicate synthesis spam is tested. +//! However, for now, these two crafting techniques remain subpar and discarding them comes at no +//! loss for the crafter. +//! +//! Others algorithm exists and could very well cover all other basis at the expense of runtime. +//! We have chosen not to implement them as they (for now) would be very unlikely to uncover anything +//! meaningful. +//! +//! ### Leveling +//! +//! We have (for now at least) no intention to release a leveling feature to the crafting solver +//! However, selecting some spells and buffs and have them disabled could be added as a feature +//! hence making a "leveling" option +//! +//! If it is ever released, this feature is likely to be heavily reliant on the python GUI. +//! //! //! ## Contributing //! //! All form of contributions are welcome ! //! -//! While this project was originnaly a collab and didn't strive to encompass every need +//! While this project was originally a collab and didn't strive to encompass every need //! of a modern FFXIV crafter, more polish and finish is always welcome. //! -//! ## Licence +//! ## License //! -//! The original code was released without a licence by [RikaKagurasaka](https://github.com/RikaKagurasaka/xiv_craft_solver) +//! The original code was released without a license by [RikaKagurasaka](https://github.com/RikaKagurasaka/xiv_craft_solver) //! //! All this fork's code is released under [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0)