From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 116365 invoked by alias); 25 Nov 2016 15:09:20 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Received: (qmail 116348 invoked by uid 89); 25 Nov 2016 15:09:19 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.9 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,SPF_PASS,URIBL_RED autolearn=ham version=3.3.2 spammy= X-HELO: relay1.mentorg.com Date: Fri, 25 Nov 2016 15:09:00 -0000 From: Joseph Myers To: Rical Jasan CC: , Michael Kerrisk , Carlos O'Donell Subject: Re: [PATCH 3/3] manual: Add new header and standards annotations. In-Reply-To: Message-ID: References: <20161123063807.14845-1-ricaljasan@pacific.net> <20161123063807.14845-4-ricaljasan@pacific.net> <64fa1a5a-4af3-5e3f-b192-e79203c3e328@pacific.net> User-Agent: Alpine 2.20 (DEB 67 2015-01-07) MIME-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" X-ClientProxiedBy: svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) To svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) X-SW-Source: 2016-11/txt/msg00924.txt.bz2 On Fri, 25 Nov 2016, Joseph Myers wrote: > I don't think you should document feature test macros (certainly not > without a very careful review that the conditionals actually make sense). To give more rationale here: Documentation should be for stable interfaces, not for implementation details. The fact that something is part of a given standard is a stable interface. The fact that something is declared under certain conditions may not be a stable interface, if for example it's an implementation detail that header X includes header Y (where the standards permit but don't require this) or defines type foo_t rather than using __foo_t. Effectively, the API to document for a header is a subset of what it actually exposes at any given time. (Every public symbol should be documented somewhere in the manual, but not necessarily for every header or feature test macro that actually exposes that symbol.) -- Joseph S. Myers joseph@codesourcery.com