[cfe-dev] Documenting Clang: question about how best to deliver the doc

[Eli Friedman]

On Mon, Aug 19, 2013 at 2:39 PM, Morrison, Michael <
Michael_Morrison at playstation.sony.com> wrote:

>  As some of you know, we at Sony Computer Entertainment America have been
> working on various aspects of LLVM, including Clang and its toolchain.  As
> part of our work, we have created documentation for our customers about
> using Clang, and we would like to share the fruits of our work with the
> Clang and LLVM communities.****
>
> ** **
>
> As our first documentation submission, we plan to provide our *CPU
> Intrinsics Guide*, which documents the Clang intrinsics for x86intrin.h,
> along with several builtin and sync types.  I've included a sample of what
> we document for one of the intrinsics below.****
>
> ** **
>
> Our question for the community is:  what documentation format is most
> helpful and desired for this information?  We currently have two main
> possibilities in mind (with three variants for the first option):****
>
> ** **
>
> 1) Add the documentation for each intrinsic to the header file:****
>
> ** **
>
> - 1a) Using Doxygen tagging.  One benefit of this approach is that the
> documentation is available for the developer within a
> code-development/editing system.  One potential difficulty with this
> approach is that the intrinsics header file becomes much larger, which
> could increase compile times.
>

Would you mind measuring this, at least approximately?  If the performance
penalty isn't substantial, I would lean towards this solution.

- 1b) Using Microsoft's annotation grammar.  We might be able to contain
> this annotation grammar within Doxygen tagging that deviates somewhat from
> the LLVM Doxygen style.  This approach allows us to generate XML output for
> the Microsoft Visual Studio Tooltip class.  The benefit of this approach is
> that the documentation is available for the developer within Visual Studio,
> without his or her having to open the specific header file.  Like option
> (1a), one potential difficulty with this approach is that the intrinsics
> header file becomes much larger, which could increase compile times.
>

It's not clear to me why you can't generate XML output if you use LLVM
Doxygen style; do you just not have a tool that can do the appropriate
conversion?

- 1c) Using TblGen to maintain both the intrinsics definitions and their
> documentation, from which we generate the header file with both.  With this
> approach, we could implement either option (1a), (1b), or both, and have a
> single point of maintenance.  This option has the same benefits and
> drawbacks as (1a) and (1b).
>

Not really a fan of this; the intrinsics headers are hard enough to read
without using some custom format.

2) Add the documentation in reST and Sphynx format (to match existing Clang
> and LLVM documentation) to the Clang Web site.  The main benefit of this
> approach is that the documentation is available to anyone on the Web.
>

If we have the docs in Doxygen format, we can convert them to HTML anyway.


> Thus, we come to you today to ask your opinion on which approach we should
> take.  We're open to providing one or more of the formats, as desired, or
> considering a different option that one of you might make.****
>
> ** **
>
> ** **
>
> Sample intrinsic documentation (ASCII formatted for forum viewing)****
>
> -------------------------------****
>
> ** **
>
> _mm256_round_ps****
>
> ** **
>
> SYNOPSIS****
>
> #include <x86intrin.h>****
>
> __m256 _mm256_round_ps(__m256 v, const int m);****
>
> ** **
>
> INSTRUCTION****
>
> VROUNDPS****
>
> ** **
>
> DESCRIPTION****
>
> Rounds the values stored in a packed 256-bit vector [8 x float] as
> specified by the byte operand. The source values are rounded to integer
> values and returned as floating point values.****
>
> ** **
>
> PARAMETERS****
>
> v              A 256-bit vector of [8 x float] values.****
>
> m            An immediate byte operand specifying how the rounding is to
> be performed.****
>
>                 Bits [7:4] are reserved.****
>
>                 Bit [3] is a precision exception value:****
>
>                                 0: A normal PE exception is used****
>
>                                 1: The PE field is not updated****
>
>                 Bit [2] is a rounding control source:****
>
>                                 0: MXCSR:RC****
>
>                                 1: Use the RC field value****
>
>                 Bit [1:0] contain the rounding control definition:****
>
>                                 00: Nearest****
>
>                                 01: Downward (toward negative infinity)***
> *
>
>                                 10: Upward (toward positive infinity)****
>
>                                 11: Truncated****
>
> ** **
>
> RETURNS****
>
> A 256-bit vector of [8 x float] containing the rounded values.****
>
> ** **
>
> -------------------------------
>

Very nice. :)

-Eli
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20130819/bbc53d49/attachment.html>