From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id A199F61B52 for ; Fri, 18 Dec 2020 09:26:16 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 983FA2D875 for ; Fri, 18 Dec 2020 09:26:16 +0100 (CET) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [212.186.127.180]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id AFADE2D86A for ; Fri, 18 Dec 2020 09:26:15 +0100 (CET) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 848F345316 for ; Fri, 18 Dec 2020 09:26:15 +0100 (CET) Date: Fri, 18 Dec 2020 09:26:05 +0100 From: Fabian =?iso-8859-1?q?Gr=FCnbichler?= To: Proxmox Backup Server development discussion , Thomas Lamprecht References: <20201217142745.661843-1-f.gruenbichler@proxmox.com> <428fc59d-c710-b129-1931-efcea562adbf@proxmox.com> In-Reply-To: <428fc59d-c710-b129-1931-efcea562adbf@proxmox.com> MIME-Version: 1.0 User-Agent: astroid/0.15.0 (https://github.com/astroidmail/astroid) Message-Id: <1608278942.pp0t2x4mo4.astroid@nora.none> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-SPAM-LEVEL: Spam detection results: 0 AWL 0.024 Adjusted score from AWL reputation of From: address KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: Re: [pbs-devel] [RFC proxmox-backup 1/3] acl: add docs and adapt visibility X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 18 Dec 2020 08:26:16 -0000 On December 17, 2020 5:12 pm, Thomas Lamprecht wrote: > On 17/12/2020 15:27, Fabian Gr=C3=BCnbichler wrote: >> document all public things, add some doc links and make some >> previously-public things only available for test cases or within the >> crate: >>=20 >> previously public, now private: >> - AclTreeNode::extract_user_roles (we have extract_roles()) >> - AclTreeNode::extract_group_roles (same) >> - AclTreeNode::delete_group_role (exists on AclTree) >> - AclTreeNode::delete_user_role (same) >> - AclTreeNode::insert_group_role (same) >> - AclTreeNode::insert_user_role (same) >> - AclTree::write_config (we have save_config()) >> - AclTree::load (we have config()/cached_config()) >>=20 >> previously public, now crate-internal: >> - AclTree::from_raw (only used by tests) >> - split_acl_path (used by some test binaries) >>=20 >=20 > thanks, thats makes it cleaner >=20 >> Signed-off-by: Fabian Gr=C3=BCnbichler >> --- >> RFC to get some feedback on which rustdoc features we actually want to >> use here, and which we want to leave out for now. >>=20 >=20 > Anything specific you want comments for, I mean I only skimmed through it= quickly=20 > so may have overlooked stuff, but it seems like its mostly links which ar= e new > in usage? >=20 > As long its a stable supported rustdoc feature available by the rust vers= ion > we use I'm all for being able to use it. >=20 yes, mainly the linking (rust 1.48 now supports proper intra-crate=20 linking without having to guess the HTML structure it creates, so this=20 should work nicely now). my main concern were the following (sorry for not taking the time to=20 write them up): nice to read links in the code (i.e., as plain as possible) don't look=20 nice in the generated docs, and vice-versa =3D> which part gets priority? e.g., the following: /// Returns applicable [Role] and their propagation status for a given /// [Authid](crate::api2::types::Authid). /// /// If the `Authid` is a [User](crate::config::user::User) that has no = specific `Roles` configured on this node, /// applicable `Group` roles will be returned instead. is not nice to parse while reading the code, but it will read much=20 better in the generated HTML than /// Returns applicable [Role] and their propagation status for a given /// [crate::api2::types::Authid] /// /// If the `Authid` is a [crate::config::user::User] that has no specif= ic `Roles` configured on this node, /// applicable `Group` roles will be returned instead. does. according to the docs the following should also work, and might=20 actually be the nicest variant: /// Returns applicable [Role] and their propagation status for a given /// [Authid]. /// /// If the `Authid` is a [User] that has no specific `Roles` configured= on this node, /// applicable `Group` roles will be returned instead. /// /// [Authid]: crate::api2::types::Authid /// [User]: crate::config::user::User a second point was that for structs we have to watch out that not too=20 much rustdoc special syntax slips into the generated API schema=20 descriptions (thankfully, examples are usually limited to functions). we=20 could try some heuristics to run on our api dump (e.g., complaining if=20 we add special syntax compared to the last tracked api dump) to catch=20 that, since we just need to override the #[api] description which takes=20 precedence over the auto-generated one to fix it. or, we could try to=20 automagically strip some stuff when using the auto-generated one. =