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

[Gedare Bloom]

On Thu, Aug 6, 2020 at 11:57 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> 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.
>   */
>
Looks good to me.

> /**
>   * @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

Thanks. It looks alright to me.