[PATCH v2 0/1] Generate application configuration option documentation

[Sebastian Huber]

On 06/08/2020 17:17, Gedare Bloom wrote:

> On Thu, Aug 6, 2020 at 7:16 AM Sebastian Huber
> <sebastian.huber at embedded-brains.de> wrote:
>> This patch adds the application configuration option documentation generated
>> from specification items:
>>
>> https://git.rtems.org/rtems-central.git/tree/spec/if/acfg
>>
>> The header file is generated by the following script and module:
>>
>> https://git.rtems.org/rtems-central.git/tree/spec2doc.py
>>
>> https://git.rtems.org/rtems-central.git/tree/rtemsqual/applconfig.py
>>
> The generated file should be identified explicitly as a generated
> file, and perhaps embed the methodology for (re)generating it as well.

What about this:

/* SPDX-License-Identifier: BSD-2-Clause */

/*
  * Copyright (C) 2019, 2020 embedded brains GmbH 
(http://www.embedded-brains.de)
  * Copyright (C) 2010 Gedare Bloom
  * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
  *    documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
"AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 
TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 
OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */

/*
  * This file was automatically generated.  Do not edit it manually.
  * Please have a look at
  *
  * https://docs.rtems.org/branches/master/eng/req/howto.html
  *
  * for information how to maintain and re-generate this file.
  */

/**
  * @defgroup RTEMSApplConfig Application Configuration Options
  *
  * @ingroup RTEMSAPI
  */

[...]

>
>> The module uses currently a hack to resolve references external to specification
>> items, e.g. sections in the RTEMS Classic API Guide or URLs.  I think we need
>> specialized specification items for these external references.
>>
>> This patch is huge and contains all application configuration options of
>> RTEMS.  The review objectives for this patch should be:
>>
>> 1. The header file name and location.
>>
> I don't mind the location cpukit/doxygen
>
> Should/could we also move cpukit/doxygen.h into that directory?
Yes, I would like to move this stuff to a common directory.
>
>> 2. The general Doxygen markup.
>>
> Can you share a generated doxygen html? (I'm being a little lazy not
> to do it myself.)
>
> I skimmed the patch and the markup/content looks fine, but it would be
> good to skim the output also.
https://ftp.rtems.org/pub/rtems/people/sebh/doc/html/index.html