Re: [PATCH 04/14] Add D front-end (GDC) config, Makefile, and manpages.

[Richard Sandiford <richard dot sandiford at arm dot com>]

I'll pretend to be a doc reviewer...

Iain Buclaw <ibuclaw@gdcproject.org> writes:
> +@page
> +@vskip 0pt plus 1filll
> +Published by the Free Software Foundation @*
> +51 Franklin Street, Fifth Floor@*
> +Boston, MA 02110-1301, USA@*

Would be good to copy the expanded GNU Press stuff from gcc.texi.

> +The @command{gdc} command is a frontend to @command{gcc} and supports many
> +of the same options.

A bit pedantic, but I think this should be something like:

  The @command{gdc} command is the GNU compiler for the D language and
  supports many of the same options as @command{gcc}.

> +@menu
> +* Input and Output files::  Controlling the kind of output:
> +                            an executable, object files, assembler files,
> +* Runtime Options::         Options controlling runtime behaviour

"behavior"

> +* Directory Options::       Where to find module files
> +* Code Generation::         Options controlling the output of gdc
> +* Warnings::                Options controlling warnings specific to gdc
> +* Linking::                 Options influceing the linking step

"influencing"

> +* Developer Options::       Options you won't use

Don't know if this came from an earlier version of the main GCC manual,
but it seems a bit off-message for the FSF.  Something boring like:

  Options useful for developers of gdc

might be better.

> +For any given input file, the file name suffix determines what kind of
> +compilation is done.  The following kinds of input file names are supported:
> +
> +@table @gcctabopt
> +@item @var{file}.d
> +D source files.
> +@item @var{file}.dd
> +Ddoc source files.
> +@item @var{file}.di
> +D interface files.
> +@end table
> +
> +You can specify more than one input file on the @command{gdc} command line,
> +in which case they will all be compiled.  If you specify a

The documentation convention is to avoid the future tense for things
like this.  s/will all be/are all/ doesn't read very naturally so it
might need to be reworded.

> +@code{-o @var{file}} option, all the input files will be compiled together,

Same here.

> +@item -fno-bounds-check
> +@cindex @option{-fbounds-check}
> +@cindex @option{-fno-bounds-check}
> +Turns off array bounds checking for all functions, which can improve
> +performance for code that uses array extensively.  Note that this

"uses arrays extensively"?  Or maybe some markup is missing from "array".

> +can result in unpredictable behavior if the code in question actually
> +does violate array bounds constraints.  It is safe to use this option
> +if you are sure that your code will never throw a @code{RangeError}.

s/will never throw/never throws/

> +@item -fno-builtin
> +@cindex @option{-fbuiltin}
> +@cindex @option{-fno-builtin}
> +Don't recognize built-in functions that do not begin with
> +@samp{__builtin_} as prefix.  By default, the compiler will recognize
> +when a function in the @code{core.stdc} package is a built-in function.

maybe "unless they begin with the prefix @samp{__builtin_}"?
s/will recognize/recognizes/

> +@table @samp
> +@item level
> +@cindex @option{-fdebug=level}
> +Sets the debug level to @var{level}, any @code{debug} code <= @var{level}
> +is compiled into the program.
> +@item ident
> +@cindex @option{-fdebug=ident}
> +Turns on compilation of any @code{debug} code identified by @var{ident}.
> +@end table

Should be @var rather than @samp in the @table.  Also @var{...} in
the @option{...}s.

> +@item -fno-moduleinfo
> +@cindex @option{-fmoduleinfo}
> +@cindex @option{-fno-moduleinfo}
> +Turns off generation of the @code{ModuleInfo} and related functions
> +that would become unreferenced without it, which may allow linking
> +to programs not written in D.  Functions that will not be generated

s/will not be/are not/

> +include module constructor and destructors (@code{static this} and

s/constructor/constructors/?  Or is there only one of each, in which
case maybe "the module constructor and destructor".

> +@item -frelease
> +@cindex @option{-frelease}
> +@cindex @option{-fno-release}
> +Turns on compiling in release mode, which means not emitting runtime
> +checks for contracts and asserts.  Array bounds checking is not done
> +for @code{@@system} and @code{@@trusted} functions, and assertion
> +failures are undefined behaviour.

"behavior"

> +This is equivalent to compiling with the following options:
> +
> +@example
> +gdc -fno-assert -fbounds-check=safe -fno-invariants \
> +    -fno-postconditions -fno-preconditions -fno-switch-errors
> +@end example
> +
> +@item -fno-switch-errors
> +@cindex @option{-fswitch-errors}
> +@cindex @option{-fno-switch-errors}
> +This option controls what code should be generated when no case is

s/should be/is/

> +matched in a @code{final switch} statement.  The default run time
> +behavior is that a @code{SwitchError} will be thrown.  Turning off

"is to throw a @code{SwitchError}"

> +@item -fversion=@var{value}
> +@cindex @option{-fversion}
> +Turns on compilation of conditional @code{version} code into the program
> +identified by any of the following values:
> +
> +@table @samp
> +@item level
> +@cindex @option{-fversion=level}
> +Sets the version level to @var{level}, any @code{version} code >= @var{level}
> +is compiled into the program.
> +@item ident
> +@cindex @option{-fversion=ident}
> +Turns on compilation of @code{version} code identified by @var{ident}.
> +@end table

Same comments as above about @var{}.

> +
> +@item -fno-weak
> +@cindex @option{-fweak}
> +@cindex @option{-fno-weak}
> +Turns off emission of instantiated declarations that can be defined in multiple
> +objects as weak or one-only symbols.  The default is to emit all public symbols
> +as weak, unless there lacks target support.  Disabling this options means that
> +common symbols are instead put in COMDAT or become private.

Maybe "unless the target lacks support for weak symbols"?

> +@item -J@var{dir}
> +@cindex @option{-J}
> +Specify a directory to use when searching for files in string imports
> +at compile time.  This switch is required in order to use
> +@code{import(file)} expressions.  Multiple @option{-J} options can be
> +used, and the paths are searched in the same order.

Should this be @var{file}?

> +@item -fmodule-file=@var{module}=@var{spec}
> +@cindex @option{-fmodule-file}
> +This option manipulates file paths of imported modules, such that if an
> +imported module matches all or the leftmost part of @var{module}, the file
> +path in @var{spec} is used as the location to search for D sources.
> +This is used when the source file path and names are not the same as the
> +package and module hierachy.  Consider the following examples:

"hierarchy"

> +@item -imultilib @var{dir}
> +@cindex @option{-imultilib}
> +Use @var{dir} as a subdirectory of the gcc directory containing
> +target-specific D sources and interfaces.

Which gcc directory does this mean?

> +@item -iprefix @var{prefix}
> +@cindex @option{-iprefix}
> +Specify @var{prefix} as the prefix for the gcc directory containing
> +target-specific D sources and interfaces.  If the @var{prefix} represents
> +a directory, you should include the final @code{'/'}.

Same here.  What does a prefix without the "/" mean here?  It doesn't
seem from the docs that it acts with a -iwithprefix option.

> +@item -nostdinc
> +@cindex @option{-nostdinc}
> +Do not search the standard system directories for D source and interface
> +files.  Only the directories that have been specified with @option{-I} options
> +(and the directory of the current file, if appropriate) are searched.

When's that appropriate for D?

> +@item -H
> +@cindex @option{-H}
> +Generates D interface files for all modules being compiled.  The compiler
> +determines the output @var{file} based on the name of the input file,
> +removes any directory components and suffix, and applies the @file{.di}
> +suffix.

Marking up @var{file} looks odd here, since nothing else refers to it.

> +@item -Hd @var{dir}
> +@cindex @option{-Hd}
> +Same as @option{-H}, but writes interface files to @var{dir} directory.

"directory @var{dir}"?

> +@item -MD
> +@cindex @option{-MD}
> +This option is equivalent to @option{-M -MF @var{file}}.  The driver
> +determines @var{file} based on the name of the input file, removes any
> +directory components and suffix, and applies a @file{.deps} suffix.

This sounded at first like the driver removes the components after
determining @var{file}, whereas I'm guessing that's how it determines
@var{file}.  Maybe something like:

  determines @var{file} by removing any directory components and suffix
  from the input file and then adding a @file{.deps} suffix.

if so?

> +@item -X
> +@cindex @option{-X}
> +Output information describing the contents of all source files being
> +compiled in JSON format to a file.  The driver determines @var{file} based
> +on the name of the input file, removes any directory components and suffix,
> +and applies a @file{.json} suffix.

Same sort of thing here.

> +@item -fdoc
> +@cindex @option{-fdoc}
> +Generates @code{Ddoc} documentation and writes to a file.  The compiler
> +determines @var{file} based on the name of the input file, removes any
> +directory components and suffix, and applies a @file{.html} suffix.

Here too.  "writes it"?

> +@item -fdoc-dir=@var{dir}
> +@cindex @option{-fdoc-dir}
> +Same as @option{-fdoc}, but writes documentation to @var{dir} directory.

"directory @var{dir}"?

> +@item -Wall
> +@cindex @option{-Wall}
> +@cindex @option{-Wno-all}
> +Turns on all warnings messages.  Warnings are not a defined part of
> +the D language, and all constructs for which this may generate a
> +warning message are legal code.

"valid code".  But I assume this is "all" in the same way that it's
"all" for C and C++?  Might be better to use something like the
invoke.texi entry, which says:

    This enables all the warnings about constructions that some users
    consider questionable, and that are easy to avoid (or modify to
    prevent the warning), even in conjunction with macros.

> +@item -Wspeculative
> +@cindex @option{-Wspeculative}
> +@cindex @option{-Wno-speculative}
> +Report on all error messages from speculative compiles, such as
> +@code{__traits(compiles, ...)}.  This option does not report
> +messages as warnings, and these messages therefore never become
> +errors when the @option{-Werror} option is also used.

"Report on all error messages" sounds a bit odd.

> +@item -Wunknown-pragmas
> +@cindex @option{-Wunknown-pragmas}
> +@cindex @option{-Wno-unknown-pragmas}
> +Warn when a @code{pragma()} is encountered that is not understood by
> +@command{gdc}.  This differs from @option{-fignore-unknown-pragmas}
> +where a pragma that is part of the D language, but not implemented by
> +the compiler, will not get reported.

Future tense.

> +@item -fsyntax-only
> +@cindex @option{-fsyntax-only}
> +@cindex @option{-fno-syntax-only}
> +Check the code for syntax errors, but do not actually compile it.  This
> +only suppresses the generation of the object code, and can be used in
> +conjunction with @option{-fdoc} or @option{-H} options.

"object code" might be confusing since I assume we wouldn't generate
assembly code either.

> +These options come into play when the compiler links object files into an
> +executable output file. They are meaningless if the compiler is not doing
> +a link step.

Two spaces before "They".

> +@item -fdump-d-original
> +@cindex @option{-fdump-d-original}
> +Dump the front-end AST after after parsing and running semantic on
> +the source program.  Only really useful for debugging the compiler
> +itself.

"after running semantic" sounds odd.  Based on -v, maybe "after the
@code{semantic} stage", if that's what it means?

Looks OK otherwise.

Thanks,
Richard