From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 6497 invoked by alias); 15 Jan 2003 19:46:31 -0000 Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org Received: (qmail 6490 invoked from network); 15 Jan 2003 19:46:29 -0000 Received: from unknown (HELO lacrosse.corp.redhat.com) (66.187.233.200) by sources.redhat.com with SMTP; 15 Jan 2003 19:46:29 -0000 Received: from tornado.toronto.redhat.com (IDENT:STc+2lhD8HXw5yhDoSd1c25PI+NRm9u1@tornado.toronto.redhat.com [172.16.14.228]) by lacrosse.corp.redhat.com (8.11.6/8.9.3) with ESMTP id h0FJkSg27711 for ; Wed, 15 Jan 2003 14:46:28 -0500 Received: from tornado.toronto.redhat.com (localhost [127.0.0.1]) by tornado.toronto.redhat.com (8.12.5/8.12.5) with ESMTP id h0FJkRpw025224 for ; Wed, 15 Jan 2003 14:46:27 -0500 Received: (from dnovillo@localhost) by tornado.toronto.redhat.com (8.12.5/8.12.5/Submit) id h0FJkROD025222 for gcc@gcc.gnu.org; Wed, 15 Jan 2003 14:46:27 -0500 Date: Wed, 15 Jan 2003 23:48:00 -0000 From: Diego Novillo To: gcc@gcc.gnu.org Subject: Thoughts on doxygen for internal documentation Message-ID: <20030115194627.GA25096@tornado.toronto.redhat.com> Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline User-Agent: Mutt/1.4i Organization: Red Hat Canada X-SW-Source: 2003-01/txt/msg00728.txt.bz2 I have tried using doxygen to document the tree-ssa API. Given the prevalent documentation style in GCC, I find some of the markers rather intrusive. For instance, it insists that documentation for arguments should be preceded by @param. It also doesn't understand that we refer to the argument names in capitals. This breaks the flow of the comment and makes it harder to read. I don't mind the @brief marker that it wants for adding one liner descriptions in the TOC. But again, I'd rather not add it. What I find nice are the @file markers for describing the file. What is really useful about doxygen is all the cross referencing and html pages it builds. Also, we don't really need to mark up everything for doxygen to be useful. It's enough that we delimit the function comments with /** */. For the tree-ssa branch, I'd like to propose the following: 1- When writing the preceding documentation for a function, data structure or variable, delimit it with /** */. This way, doxygen will add it when generating documentation. 2- For new files use the @file and @brief markers to provide a brief description for the file. No other markers should be required. It would be nice if the rest of the compiler used the /** */ comments, but for now I'm happy if we just do it for the tree-ssa files. Thoughts? Diego.