From 47605742d473c0bd0f231f7a73bf401dad172549 Mon Sep 17 00:00:00 2001 From: Jan-Niklas Burfeind Date: Thu, 25 Jul 2024 16:44:10 +0200 Subject: [PATCH 1/7] docs: Fix broken internal links --- lib/src/client/builder.rs | 4 ---- lib/src/client/mod.rs | 5 ----- lib/src/server/server.rs | 2 +- 3 files changed, 1 insertion(+), 10 deletions(-) diff --git a/lib/src/client/builder.rs b/lib/src/client/builder.rs index e802f15c1..12d893dd6 100644 --- a/lib/src/client/builder.rs +++ b/lib/src/client/builder.rs @@ -24,8 +24,6 @@ impl ClientBuilder { /// Yields a [`Client`] from the values set by the builder. If the builder is not in a valid state /// it will return `None`. - /// - /// [`Client`]: client/struct.Client.html pub fn client(self) -> Option { if self.is_valid() { Some(Client::new(self.config)) @@ -35,8 +33,6 @@ impl ClientBuilder { } /// Yields a [`ClientConfig`] from the values set by the builder. - /// - /// [`ClientConfig`]: ../config/struct.ClientConfig.html pub fn config(self) -> ClientConfig { self.config } diff --git a/lib/src/client/mod.rs b/lib/src/client/mod.rs index 517f84de7..0756fdf4d 100644 --- a/lib/src/client/mod.rs +++ b/lib/src/client/mod.rs @@ -104,11 +104,6 @@ //! } //!} //! ``` -//! -//! [`Client`]: ./client/struct.Client.html -//! [`ClientConfig`]: ./config/struct.ClientConfig.html -//! [`ClientBuilder`]: ./client_builder/struct.ClientBuilder.html -//! [`Session`]: ./session/struct.Session.html mod builder; mod config; diff --git a/lib/src/server/server.rs b/lib/src/server/server.rs index 4bb666000..5372c044f 100644 --- a/lib/src/server/server.rs +++ b/lib/src/server/server.rs @@ -58,7 +58,7 @@ pub type Connections = Vec>>; /// [`run_server`]: #method.run_server /// [`ServerConfig`]: ../config/struct.ServerConfig.html /// [`AddressSpace`]: ../address_space/address_space/struct.AddressSpace.html -/// [`CertificateStore`]: ../../opcua_core/crypto/certificate_store/struct.CertificateStore.html +/// [`CertificateStore`]: ../../crypto/certificate_store/struct.CertificateStore.html /// pub struct Server { /// List of pending polling actions to add to the server once run is called From 715909bb34495dc4d2921dfcd879875a952cec34 Mon Sep 17 00:00:00 2001 From: Jan-Niklas Burfeind Date: Thu, 25 Jul 2024 14:09:28 +0200 Subject: [PATCH 2/7] ci: Verify all links are alive Use cargo-binstall to avoid building cargo-deadcode from source in CI. --- .github/workflows/ci_docs.yml | 21 +++++++++++++++++++++ .github/workflows/main.yml | 3 +++ 2 files changed, 24 insertions(+) create mode 100644 .github/workflows/ci_docs.yml diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml new file mode 100644 index 000000000..f991b4774 --- /dev/null +++ b/.github/workflows/ci_docs.yml @@ -0,0 +1,21 @@ +name: Verify documentation integrity +'on': + workflow_call: null +jobs: + cov: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: cargo-bins/cargo-binstall@v1.7.4 + - name: Install cargo-deadlinks binary + run: cargo binstall cargo-deadlinks@0.8.1 --no-confirm + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Check for dead links in docs + run: cargo deadlinks + + - name: Check for dead https(s) links in docs + # `no-build` is passed, as the first invocation of `cargo deadlinks` already built the docs + run: cargo deadlinks --check-http --no-build diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 1cdfb7a4f..1cfc028e7 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -51,6 +51,9 @@ jobs: code-coverage: uses: ./.github/workflows/ci_code_coverage.yml + docs: + uses: ./.github/workflows/ci_docs.yml + verify-clean-address-space: uses: ./.github/workflows/ci_verify_clean_address_space.yml From 6633927cd4f024de5b861fb38afae794ab0c460b Mon Sep 17 00:00:00 2001 From: Jan-Niklas Burfeind Date: Thu, 25 Jul 2024 17:11:57 +0200 Subject: [PATCH 3/7] docs: Omit reference to private members in public docs which would lead to internal dead links. --- lib/src/client/session/client.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/src/client/session/client.rs b/lib/src/client/session/client.rs index fd11b279f..a3b57e38f 100644 --- a/lib/src/client/session/client.rs +++ b/lib/src/client/session/client.rs @@ -197,7 +197,7 @@ impl Client { .unwrap()) } - /// Connects to an a server directly using provided [`SessionInfo`]. + /// Connects to a server directly using provided SessionInfo. /// /// This function returns both a reference to the session, and a `SessionEventLoop`. You must run and /// poll the event loop in order to actually establish a connection. From a6d31b830d5e96b0d9e5eeb7b72a62e4bfacc582 Mon Sep 17 00:00:00 2001 From: Jan-Niklas Burfeind Date: Thu, 25 Jul 2024 17:13:51 +0200 Subject: [PATCH 4/7] docs: Fix naming of structs in docstrings according to their documented functions signature. --- lib/src/client/session/client.rs | 4 ++-- lib/src/client/session/services/attributes.rs | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/src/client/session/client.rs b/lib/src/client/session/client.rs index a3b57e38f..a95973971 100644 --- a/lib/src/client/session/client.rs +++ b/lib/src/client/session/client.rs @@ -237,7 +237,7 @@ impl Client { } } - /// Creates a new [`AsyncSession`] using the default endpoint specified in the config. If + /// Creates a new [`Session`] using the default endpoint specified in the config. If /// there is no default, or the endpoint does not exist, this function will return an error /// /// This function returns both a reference to the session, and a `SessionEventLoop`. You must run and @@ -264,7 +264,7 @@ impl Client { self.new_session_from_info(session_info) } - /// Creates a new [`AsyncSession`] using the named endpoint id. If there is no + /// Creates a new [`Session`] using the named endpoint id. If there is no /// endpoint of that id in the config, this function will return an error /// /// This function returns both a reference to the session, and a `SessionEventLoop`. You must run and diff --git a/lib/src/client/session/services/attributes.rs b/lib/src/client/session/services/attributes.rs index 42a1688f7..4d72cc30f 100644 --- a/lib/src/client/session/services/attributes.rs +++ b/lib/src/client/session/services/attributes.rs @@ -253,7 +253,7 @@ impl Session { /// /// # Returns /// - /// * `Ok(Vec)` - A list of [`ClientHistoryUpdateResult`] results corresponding to history update operation. + /// * `Ok(Vec)` - A list of [`HistoryUpdateResult`] results corresponding to history update operation. /// * `Err(StatusCode)` - Request failed, [Status code](StatusCode) is the reason for failure. /// pub async fn history_update( From 3f63fcc0718c9977417815145d791c91a5d45052 Mon Sep 17 00:00:00 2001 From: Jan-Niklas Burfeind Date: Thu, 25 Jul 2024 17:14:51 +0200 Subject: [PATCH 5/7] docs: Escape brackets not meant as hyperlink markers --- lib/src/crypto/certificate_store.rs | 2 +- lib/src/types/array.rs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/src/crypto/certificate_store.rs b/lib/src/crypto/certificate_store.rs index 841ccc388..173eacae5 100644 --- a/lib/src/crypto/certificate_store.rs +++ b/lib/src/crypto/certificate_store.rs @@ -410,7 +410,7 @@ impl CertificateStore { } /// Returns a certificate file name from the cert's issuer and thumbprint fields. - /// File name is either "prefix - [thumbprint].der" or "thumbprint.der" depending on + /// File name is either "prefix - \[thumbprint\].der" or "thumbprint.der" depending on /// the cert's common name being empty or not pub fn cert_file_name(cert: &X509) -> String { let prefix = if let Ok(common_name) = cert.common_name() { diff --git a/lib/src/types/array.rs b/lib/src/types/array.rs index 05aea11d1..f0d4398e3 100644 --- a/lib/src/types/array.rs +++ b/lib/src/types/array.rs @@ -13,8 +13,8 @@ pub struct Array { /// Multi dimension array which can contain any scalar type, all the same type. Nested /// arrays are rejected. Higher rank dimensions are serialized first. For example an array - /// with dimensions [2,2,2] is written in this order - [0,0,0], [0,0,1], [0,1,0], [0,1,1], - /// [1,0,0], [1,0,1], [1,1,0], [1,1,1]. + /// with dimensions \[2,2,2\] is written in this order - \[0,0,0\], \[0,0,1\], \[0,1,0\], + /// \[0,1,1\], \[1,0,0\], \[1,0,1\], \[1,1,0\], \[1,1,1\]. pub dimensions: Option>, } From cb28b7f373f5d73d18c9e7abcf14179e5a5059d7 Mon Sep 17 00:00:00 2001 From: Jan-Niklas Burfeind Date: Thu, 25 Jul 2024 17:15:46 +0200 Subject: [PATCH 6/7] docs: Mark hyperlinks in order te be rendered as such --- lib/src/crypto/hash.rs | 4 ++-- lib/src/crypto/pkey.rs | 2 +- lib/src/crypto/security_policy.rs | 20 ++++++++++---------- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/lib/src/crypto/hash.rs b/lib/src/crypto/hash.rs index 889dd5b14..6d5a3c2f7 100644 --- a/lib/src/crypto/hash.rs +++ b/lib/src/crypto/hash.rs @@ -14,8 +14,8 @@ use super::{SHA1_SIZE, SHA256_SIZE}; /// Pseudo random `P_SHA` implementation for creating pseudo random range of bytes from an input /// -/// https://www.ietf.org/rfc/rfc4346.txt -/// https://tools.ietf.org/html/rfc5246 +/// +/// /// /// P_SHA1(secret, seed) = HMAC_SHA1(secret, A(1) + seed) + /// HMAC_SHA1(secret, A(2) + seed) + diff --git a/lib/src/crypto/pkey.rs b/lib/src/crypto/pkey.rs index b69a4fec2..75deac96f 100644 --- a/lib/src/crypto/pkey.rs +++ b/lib/src/crypto/pkey.rs @@ -370,7 +370,7 @@ impl PublicKey { /// This module contains a bunch of nasty stuff to implement OAEP-SHA256 since there are no helpers in OpenSSL to do it /// -/// https://stackoverflow.com/questions/17784022/how-to-encrypt-data-using-rsa-with-sha-256-as-hash-function-and-mgf1-as-mask-ge +/// mod oaep_sha256 { use foreign_types::ForeignType; use libc::*; diff --git a/lib/src/crypto/security_policy.rs b/lib/src/crypto/security_policy.rs index 298b9d182..2339d8b65 100644 --- a/lib/src/crypto/security_policy.rs +++ b/lib/src/crypto/security_policy.rs @@ -108,11 +108,11 @@ mod basic_256_sha_256 { /// Basic128Rsa15 security policy (deprecated in OPC UA 1.04) /// -/// AsymmetricSignatureAlgorithm – RsaSha1 – (http://www.w3.org/2000/09/xmldsig#rsa-sha1). -/// AsymmetricEncryptionAlgorithm – Rsa15 – (http://www.w3.org/2001/04/xmlenc#rsa-1_5). -/// SymmetricSignatureAlgorithm – HmacSha1 – (http://www.w3.org/2000/09/xmldsig#hmac-sha1). -/// SymmetricEncryptionAlgorithm – Aes128 – (http://www.w3.org/2001/04/xmlenc#aes128-cbc). -/// KeyDerivationAlgorithm – PSha1 – (http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/dk/p_sha1). +/// AsymmetricSignatureAlgorithm – RsaSha1 – (). +/// AsymmetricEncryptionAlgorithm – Rsa15 – (). +/// SymmetricSignatureAlgorithm – HmacSha1 – (). +/// SymmetricEncryptionAlgorithm – Aes128 – (). +/// KeyDerivationAlgorithm – PSha1 – (). /// /// # Limits /// @@ -135,11 +135,11 @@ mod basic_128_rsa_15 { /// Basic256 security policy (deprecated in OPC UA 1.04) /// -/// AsymmetricSignatureAlgorithm – RsaSha1 – (http://www.w3.org/2000/09/xmldsig#rsa-sha1). -/// AsymmetricEncryptionAlgorithm – RsaOaep – (http://www.w3.org/2001/04/xmlenc#rsa-oaep). -/// SymmetricSignatureAlgorithm – HmacSha1 – (http://www.w3.org/2000/09/xmldsig#hmac-sha1). -/// SymmetricEncryptionAlgorithm – Aes256 – (http://www.w3.org/2001/04/xmlenc#aes256-cbc). -/// KeyDerivationAlgorithm – PSha1 – (http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512/dk/p_sha1). +/// AsymmetricSignatureAlgorithm – RsaSha1 – (). +/// AsymmetricEncryptionAlgorithm – RsaOaep – (). +/// SymmetricSignatureAlgorithm – HmacSha1 – (). +/// SymmetricEncryptionAlgorithm – Aes256 – (). +/// KeyDerivationAlgorithm – PSha1 – (). /// /// # Limits /// From d567110f45cd3f80d23cedb2b71b7326f9db7ba8 Mon Sep 17 00:00:00 2001 From: Jan-Niklas Burfeind Date: Thu, 25 Jul 2024 17:19:47 +0200 Subject: [PATCH 7/7] ci: Check for doc warnings while regular build warnings are ignored in this stage. --- .github/workflows/ci_docs.yml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index f991b4774..cb1319927 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -7,15 +7,19 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Build documentation - treat doc warnings as problems + run: RUSTDOCFLAGS="-D warnings" cargo doc + - uses: cargo-bins/cargo-binstall@v1.7.4 - name: Install cargo-deadlinks binary run: cargo binstall cargo-deadlinks@0.8.1 --no-confirm env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + # `no-build` is passed, as we already built the docs - name: Check for dead links in docs - run: cargo deadlinks + run: cargo deadlinks --no-build - name: Check for dead https(s) links in docs - # `no-build` is passed, as the first invocation of `cargo deadlinks` already built the docs run: cargo deadlinks --check-http --no-build