From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-5.3 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_SANE_1 autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1E290C433DF for ; Fri, 31 Jul 2020 01:16:36 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id E014921744 for ; Fri, 31 Jul 2020 01:16:35 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=kernel.org header.i=@kernel.org header.b="P6bhlhRb" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org E014921744 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1k1Jee-0008QK-CF; Fri, 31 Jul 2020 01:16:12 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1k1Jec-0008QF-OW for xen-devel@lists.xenproject.org; Fri, 31 Jul 2020 01:16:10 +0000 X-Inumbo-ID: 6aa3b138-d2cb-11ea-8df9-bc764e2007e4 Received: from mail.kernel.org (unknown [198.145.29.99]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id 6aa3b138-d2cb-11ea-8df9-bc764e2007e4; Fri, 31 Jul 2020 01:16:10 +0000 (UTC) Received: from localhost (c-67-164-102-47.hsd1.ca.comcast.net [67.164.102.47]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 20744208E4; Fri, 31 Jul 2020 01:16:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1596158169; bh=+/WozuFjWE7vvJYgQCOsmMDkf3muLMjbRPBlc7Gn768=; h=Date:From:To:cc:Subject:In-Reply-To:References:From; b=P6bhlhRb86o/7urfxeC/miJn9H84X7Oh4EKBhkVJqbjc0d/Ec2RIiobcU2qvUjlHb oO8+OFwRnfuv+bvax3UVfFkT8JN+bEN6GlYENQwrTDwF/Wfk4ycQY+bKvHCClqjeT4 cVWCl/ar73l26tW/JkXr15ENMOW7KGZId/xNSeOM= Date: Thu, 30 Jul 2020 18:16:08 -0700 (PDT) From: Stefano Stabellini X-X-Sender: sstabellini@sstabellini-ThinkPad-T480s To: Ian Jackson Subject: Re: kernel-doc and xen.git In-Reply-To: <24354.50708.138178.815210@mariner.uk.xensource.com> Message-ID: References: <785FBD2D-A67C-4740-9C5B-2ECCD0AEBFFC@citrix.com> <24354.50708.138178.815210@mariner.uk.xensource.com> User-Agent: Alpine 2.21 (DEB 202 2017-01-01) MIME-Version: 1.0 Content-Type: multipart/mixed; BOUNDARY="8323329-1959419991-1596128184=:1767" Content-ID: X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: "xen-devel@lists.xenproject.org" , Stefano Stabellini , Committers , George Dunlap , "Bertrand.Marquis@arm.com" Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. --8323329-1959419991-1596128184=:1767 Content-Type: text/plain; CHARSET=UTF-8 Content-Transfer-Encoding: 8BIT Content-ID: On Thu, 30 Jul 2020, Ian Jackson wrote: > George Dunlap writes ("Re: kernel-doc and xen.git"): > > > On Jul 30, 2020, at 2:27 AM, Stefano Stabellini wrote: > ... > > > I did give a look at kernel-doc and it is very promising. kernel-doc is > > > a script that can generate nice rst text documents from in-code > > > comments. (The generated rst files can then be used as input for sphinx > > > to generate html docs.) The comment syntax [2] is simple and similar to > > > Doxygen: > > > > > > /** > > > * function_name() - Brief description of function. > > > * @arg1: Describe the first argument. > > > * @arg2: Describe the second argument. > > > * One can provide multiple line descriptions > > > * for arguments. > > > */ > > > > > > kernel-doc is actually better than Doxygen because it is a much simpler > > > tool, one we could customize to our needs and with predictable output. > > > Specifically, we could add the tagging, numbering, and referencing > > > required by FuSa requirement documents. > > > > > > I would like your feedback on whether it would be good to start > > > converting xen.git in-code comments to the kernel-doc format so that > > > proper documents can be generated out of them. One day we could import > > > kernel-doc into xen.git/scripts and use it to generate a set of html > > > documents via sphinx. > > > > `git-grep ‘^/\*\*$’ ` turns up loads of instances of kernel-doc-style comments in the tree already. I think it makes complete sense to: > > > > 1. Start using tools to pull the existing ones into sphinx docs > > 2. Skim through the existing ones to make sure they’re accurate / useful > > 3. Add such comments for elements of key importance to the FUSA SIG > > 4. Encourage people include documentation for new features, &c > > I have no objection to this. Indeed switching to something the kernel > folks find useable is likely to be a good idea. > > We should ideally convert the existing hypercall documentation, which > is parsed from a bespoke magic comment format by a script in xen.git. I agree. Great, thank you both for the feedback! --8323329-1959419991-1596128184=:1767--