Mercurial > hg > CbC > CbC_gcc

comparison gcc/doc/ux.texi @ 145:1830386684a0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
gcc-9.2.0
author anatofuz
date Thu, 13 Feb 2020 11:34:05 +0900
parents 84e7813d76e9
children
comparison
equal deleted inserted replaced
131:84e7813d76e9 145:1830386684a0
1 @c Copyright (C) 2018 Free Software Foundation, Inc. 1 @c Copyright (C) 2018-2020 Free Software Foundation, Inc.
2 @c Free Software Foundation, Inc. 2 @c Free Software Foundation, Inc.
3 @c This is part of the GCC manual. 3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi. 4 @c For copying conditions, see the file gcc.texi.
5 5
6 @node User Experience Guidelines 6 @node User Experience Guidelines
7 @chapter User Experience Guidelines 7 @chapter User Experience Guidelines
8 @cindex user experience guidelines 8 @cindex user experience guidelines
9 @cindex guidelines, user experience 9 @cindex guidelines, user experience
10 10
11 To borrow a slogan from 11 To borrow a slogan from
12 @uref{https://elm-lang.org/blog/compilers-as-assistants, Elm}, 12 @uref{https://elm-lang.org/news/compilers-as-assistants, Elm},
13 13
14 @quotation 14 @quotation
15 @strong{Compilers should be assistants, not adversaries.} A compiler should 15 @strong{Compilers should be assistants, not adversaries.} A compiler should
16 not just detect bugs, it should then help you understand why there is a bug. 16 not just detect bugs, it should then help you understand why there is a bug.
17 It should not berate you in a robot voice, it should give you specific hints 17 It should not berate you in a robot voice, it should give you specific hints
141 @item 141 @item
142 the argument count at a call site does not match the parameter count 142 the argument count at a call site does not match the parameter count
143 at the declaration 143 at the declaration
144 144
145 @item 145 @item
146 something is erroneously duplicated (e.g. an error, due to breaking a 146 something is erroneously duplicated (e.g.@: an error, due to breaking a
147 uniqueness requirement, or a warning, if it's suggestive of a bug) 147 uniqueness requirement, or a warning, if it's suggestive of a bug)
148 148
149 @item 149 @item
150 an ``opened'' syntactic construct (such as an open-parenthesis) is not 150 an ``opened'' syntactic construct (such as an open-parenthesis) is not
151 closed 151 closed
374 @noindent 374 @noindent
375 where the @code{double} and @code{int} are colorized to highlight them. 375 where the @code{double} and @code{int} are colorized to highlight them.
376 376
377 @c %H and %I were added in r248698. 377 @c %H and %I were added in r248698.
378 378
379 @subsection Group logically-related diagnostics
380
379 Use @code{auto_diagnostic_group} when issuing multiple related 381 Use @code{auto_diagnostic_group} when issuing multiple related
380 diagnostics (seen in various examples on this page). This informs the 382 diagnostics (seen in various examples on this page). This informs the
381 diagnostic subsystem that all diagnostics issued within the lifetime 383 diagnostic subsystem that all diagnostics issued within the lifetime
382 of the @code{auto_diagnostic_group} are related. (Currently it doesn't 384 of the @code{auto_diagnostic_group} are related. For example,
383 do anything with this information, but we may implement that in the 385 @option{-fdiagnostics-format=json} will treat the first diagnostic
384 future). 386 emitted within the group as a top-level diagnostic, and all subsequent
387 diagnostics within the group as its children.
388
389 @subsection Quoting
390 Text should be quoted by either using the @samp{q} modifier in a directive
391 such as @samp{%qE}, or by enclosing the quoted text in a pair of @samp{%<}
392 and @samp{%>} directives, and never by using explicit quote characters.
393 The directives handle the appropriate quote characters for each language
394 and apply the correct color or highlighting.
395
396 The following elements should be quoted in GCC diagnostics:
397
398 @itemize @bullet
399 @item
400 Language keywords.
401 @item
402 Tokens.
403 @item
404 Boolean, numerical, character, and string constants that appear in the
405 source code.
406 @item
407 Identifiers, including function, macro, type, and variable names.
408 @end itemize
409
410 Other elements such as numbers that do not refer to numeric constants that
411 appear in the source code should not be quoted. For example, in the message:
412
413 @smallexample
414 argument %d of %qE must be a pointer type
415 @end smallexample
416
417 @noindent
418 since the argument number does not refer to a numerical constant in the
419 source code it should not be quoted.
385 420
386 @subsection Spelling and Terminology 421 @subsection Spelling and Terminology
387 422
388 See the @uref{https://gcc.gnu.org/codingconventions.html#Spelling 423 See the @uref{https://gcc.gnu.org/codingconventions.html#Spelling
389 Spelling, terminology and markup} section of the GCC coding conventions. 424 Spelling, terminology and markup} section of the GCC coding conventions.
397 432
398 They are printed by default underneath the code in question. They 433 They are printed by default underneath the code in question. They
399 can also be viewed via @option{-fdiagnostics-generate-patch} and 434 can also be viewed via @option{-fdiagnostics-generate-patch} and
400 @option{-fdiagnostics-parseable-fixits}. With the latter, an IDE 435 @option{-fdiagnostics-parseable-fixits}. With the latter, an IDE
401 ought to be able to offer to automatically apply the suggested fix. 436 ought to be able to offer to automatically apply the suggested fix.
437
438 Fix-it hints contain code fragments, and thus they should not be marked
439 for translation.
402 440
403 Fix-it hints can be added to a diagnostic by using a @code{rich_location} 441 Fix-it hints can be added to a diagnostic by using a @code{rich_location}
404 rather than a @code{location_t} - the fix-it hints are added to the 442 rather than a @code{location_t} - the fix-it hints are added to the
405 @code{rich_location} using one of the various @code{add_fixit} member 443 @code{rich_location} using one of the various @code{add_fixit} member
406 functions of @code{rich_location}. They are documented with 444 functions of @code{rich_location}. They are documented with
508 warning_at (&richloc, OPT_Wredundant_move, 546 warning_at (&richloc, OPT_Wredundant_move,
509 "redundant move in return statement"); 547 "redundant move in return statement");
510 @end smallexample 548 @end smallexample
511 549
512 @noindent 550 @noindent
513 which is intended to e.g. replace a @code{std::move} with the underlying 551 which is intended to e.g.@: replace a @code{std::move} with the underlying
514 value: 552 value:
515 553
516 @smallexample 554 @smallexample
517 return std::move (retval); 555 return std::move (retval);
518 ~~~~~~~~~~^~~~~~~~ 556 ~~~~~~~~~~^~~~~~~~