From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wm1-f51.google.com (mail-wm1-f51.google.com [209.85.128.51]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D188D49B5B5 for ; Thu, 8 Oct 2026 13:13:44 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.51 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1791465226; cv=none; b=kW2vjabAz/EqivbxsBecbiLWNnXYO0v0AC9wio/lfRIno7rkaf7kJcC/Hu8AA2wjWRg//NOzSulKrg3vWNHr5RgfGmS/Cab0JDekelPHwLBDLcoB4Pxwll69gu/rkwVlhYJrBjyLtUdZ4E0QLiusyVDKrEBC58ZJeNMfn6BoroE= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1791465226; c=relaxed/simple; bh=7qtI5gtgg8HMBmacX6qKEDXcXJKwtRBJ+yKlbMqIu+U=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=gtnhoqorOu2eocQ85mq+fuFdHCeXIWBkwvj5ZcJafRcB/T+2u+wxXx9NWsangaPF2KbeTd5Q3cqzmiIWVilVc7wEziqkbtE8y6h285uVyOL033SGHUIDJDiXexkyB4FTZSp7U3k+n4LEME89bCkoA+7uv3ZFwGGBK+RhhY1LGuk= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=gourry.net; spf=pass smtp.mailfrom=gourry.net; dkim=pass (2048-bit key) header.d=gourry.net header.i=@gourry.net header.b=D1SCMzeS; arc=none smtp.client-ip=209.85.128.51 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=gourry.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gourry.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gourry.net header.i=@gourry.net header.b="D1SCMzeS" Received: by mail-wm1-f51.google.com with SMTP id 5b1f17b1804b1-4a020e65269so23129045e9.2 for ; Thu, 08 Oct 2026 06:13:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gourry.net; s=google; t=1791465223; x=1792070023; darn=vger.kernel.org; h=in-reply-to:content-disposition:content-type:mime-version :references:message-id:subject:cc:to:from:date:from:to:cc:subject :date:message-id:reply-to:content-type; bh=HO3C9RpYvCSZ09L6Ew5V40K2HpvgcXSKkDoFhjI9Kx4=; b=D1SCMzeSC+3lNkcoGtnd5MZUOxDZCN3wuNj/aDJI/4LcSRRqrhAqs/Hi9CUNMcqHFF scv7iSSgs0pq4DXVtxK1HcP+TX2UMEUKqgjygaUCO4jjwffdRYQ35mFnULVYKtlpTSr2 NHsGPcZZ4Ck5RTw+UneynMefAFGqW4jY2LdZvX3S5iBQvtZZpf3hZOieucAkZf24jP9V NxADxxZhMnMZ1FL/SL8HTUDY6ROMGb323/c7WVSmvIz551S/ndHuV25o7mDAi9hg1ccq PKvBQP/BYKJM244I8ccBCcDKG4NhIg676rJptZyeAXQKxlYl94D2DZjm9gOjO6SQD5pl U8dA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1791465223; x=1792070023; h=in-reply-to:content-disposition:content-type:mime-version :references:message-id:subject:cc:to:from:date:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=HO3C9RpYvCSZ09L6Ew5V40K2HpvgcXSKkDoFhjI9Kx4=; b=1wlRbJy+0Ex6n/eJgTOt5lVV1nmQMLbiBsjbE7JHkuM2epkPd27fzUVVhtYU3CAXc5 IuV1JSR3UmP4c3YrIAvzirbjgW/4JKxQWeIyL4WUHJvtwN+7G1hvtFXHRDFsGUah7946 0qvEos/F4MAs+yIjn5Mrj/YFoDBHWKLOmbqZl7ELFQGTsin4b4/qRMr9Xpu6+I8HTylZ Jb0KzDKlK0oL5v7pw4QVHoAk+VjN8REOh0xfMyBuqvFUbZRUTAD8R1TxnGMt2QZ5QyNy 6RK4K8Fc63MvYkG8XN94yECqusYVhIKyRLX+a+DTkYCKZ26PcvSJHDayDFZ4nYOfBBeT ZJlw== X-Forwarded-Encrypted: i=1; AKwUvBzo/+FooQ2RBZE7+gxrY0IceyNW/QtbKaYu+BQrGXK1SDiIbC46tDegRMlMGcYMb14jngUcs8xqB9s=@vger.kernel.org X-Gm-Message-State: AFuF++l9dUX/UergFIHWffaA3ycX7wDom0/z06agW9pZbL9ZA9x//6Xq koAZD8szZRM5fOozi4G59sRiFIZwla6Tm1OOOO5hM125OLfBwYrNAE8g0qevJGr/7oE= X-Gm-Gg: AYBFou3UmC5MS17l/Hi7J5krLITCPi6pHJwVxC/I+tEjIZE3O8UFhxDAk6M6pUYdcG4 wK6YicZBb7wWZjloAlu1gIvdUZdP/ErDiL+C989adM56foUUVrqqE0KbZwu+mDm4UsxOVmw6J7u WmNDvly6ioNq9dVotHwrMVGhM1vZNpec84ZuUsasEbUPPXgu+8yLq84dTeXrDoUSiB08VseLF8R tm83P3W5ubpUxDRRarQ9qMNmXiYRYvZxqX1L80hQO91ny20Gg8DUVhKLMN3a2BuuFYb14ZIzDZm F4krWHabDDcUb2xusfD6A+AZFcTfR/FdGgCom7Ab0i9xapRcx5l+a4xMqlTKX77d3QvLmjIgoF+ X+jS0SHTYO93usDe7e3Sk11a4aSmeDAR1aFvVuqt9cJ9OrTKRXl+xuGKPR+BqwxfAe/2JuQfDEf iSY6uOSk7zDMqUFKylj3mBGofIsNd5tHRwUGzkKUEhZUz3ds2AJmuHzWvmepNPLccmXMZX7ZqSG C11x1IiZw== X-Received: by 2002:a05:600c:19c7:b0:4a1:70f0:ac2 with SMTP id 5b1f17b1804b1-4a180648d69mr101498205e9.24.1791465222920; Thu, 08 Oct 2026 06:13:42 -0700 (PDT) Received: from gourry-fedora-PF4VCD3F ([185.194.184.20]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4a17f493761sm221404825e9.2.2026.10.08.06.13.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 08 Oct 2026 06:13:41 -0700 (PDT) Date: Thu, 8 Oct 2026 09:13:38 -0400 From: Gregory Price To: "Serge E. Hallyn" Cc: Sasha Levin , linux-api@vger.kernel.org, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kselftest@vger.kernel.org, workflows@vger.kernel.org, tools@kernel.org, x86@kernel.org, Thomas Gleixner , "Paul E . McKenney" , Greg Kroah-Hartman , Jonathan Corbet , Dmitry Vyukov , Randy Dunlap , Cyril Hrubis , Kees Cook , Jake Edge , David Laight , Gabriele Paoloni , Mauro Carvalho Chehab , Christian Brauner , Alexander Viro , Andrew Morton , Masahiro Yamada , Shuah Khan , Arnd Bergmann , Nathan Chancellor , Steven Rostedt , Masami Hiramatsu , Mathieu Desnoyers Subject: Re: [PATCH v5 05/11] kernel/api: add API specification for sys_open Message-ID: References: <20261008084956.2911790-1-sashal@kernel.org> <20261008084956.2911790-6-sashal@kernel.org> Precedence: bulk X-Mailing-List: workflows@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: On Thu, Oct 08, 2026 at 07:49:34AM -0500, Serge E. Hallyn wrote: > On Thu, Oct 08, 2026 at 04:49:45AM -0400, Sasha Levin wrote: > > Add KAPI-annotated kerneldoc for the sys_open system call in fs/open.c. > > > > The specification documents parameter constraints (pathname, flags > > bitmask, permission mode), 24 error conditions, locking requirements, > > side effects, required capabilities, and usage examples. > > > > Assisted-by: LLM > > Signed-off-by: Sasha Levin > > I know Kees and Jonathan and others asked for exactly this. But one > downside to this is it makes just paging through fs/open.c a lot more > painful. Maybe it's worth it. Maybe "noone will ever do that again" bc > that's why we have ai and tools. But a) that's how I've historically > done a lot of code research, b) IMO something like a manpages section 2 > under Documentation/ would be a great place for this, and c) we can also > use tools to always sync these, or even show/edit in a single view when > you want ('kdocedit fs/open.c'). > In many, many other projects i've worked on, these docs are placed in the header as opposed to the .c file, but I understand there is some pain that comes with ifdef. Keeping it in the header ties the definition to exactly the location external users import to find the function - so it makes sense. But separating the contracts from the code guarantees they'll go stale, so I don't think shoving it in Documentation/ does anyone any good. ~Gregory