mirror/binutils-gdb
2
0
Fork 0
mirror of https://sourceware.org/git/binutils-gdb.git synced 2025-02-17 13:10:12 +08:00
Code Issues Packages Projects Releases Wiki Activity
6e46bdf64e
binutils-gdb/bfd/doc/proto.str

175 lines
4.1 KiB
Plaintext
Raw Normal View History

Add copyright headers to the .str files The .str script files don't have copyright headers, but I think they should. I used the same dates that chew.c uses, which I think makes sense because these are inputs to chew. 2023-02-07 Tom Tromey <tom@tromey.com> * doc/doc.str, doc/proto.str: Add copyright header.
2023-02-08 02:39:16 +08:00
- Source extraction program for chew.
Update year range in copyright notice of binutils files Adds two new external authors to etc/update-copyright.py to cover bfd/ax_tls.m4, and adds gprofng to dirs handled automatically, then updates copyright messages as follows: 1) Update cgen/utils.scm emitted copyrights. 2) Run "etc/update-copyright.py --this-year" with an extra external author I haven't committed, 'Kalray SA.', to cover gas testsuite files (which should have their copyright message removed). 3) Build with --enable-maintainer-mode --enable-cgen-maint=yes. 4) Check out */po/*.pot which we don't update frequently.
2024-01-04 19:52:08 +08:00
- Copyright (C) 1990-2024 Free Software Foundation, Inc.
Add copyright headers to the .str files The .str script files don't have copyright headers, but I think they should. I used the same dates that chew.c uses, which I think makes sense because these are inputs to chew. 2023-02-07 Tom Tromey <tom@tromey.com> * doc/doc.str, doc/proto.str: Add copyright header.
2023-02-08 02:39:16 +08:00
- This file is part of BFD, the Binary File Descriptor library.
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 3 of the License, or
- (at your option) any later version.
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA.
19990502 sourceware import
1999-05-03 15:29:11 +08:00
Generated docs and include files bfd/doc/chew.c extracts documentation from source code comments annotated with keywords, and generates much of bfd.h and libbfd.h from those same comments. The docs have suffered from people (me too) adding things like CODE_FRAGMENT to the source to put code into bfd.h without realising that CODE_FRAGMENT also puts @example around said code into the docs. So we have random senseless things in the docs. This patch fixes that problem (well, the senseless things from CODE_FRAGMENT), moves most of the code out of bfd-in.h, and improves a few chew.c features. libbfd.h now automatically gets ATTRIBUTE_HIDDEN prototypes, and indentation in bfd.h and libbfd.h is better.
2023-04-30 19:12:30 +08:00
- chew.c keywords defined here put output into bfd-in2.h and libbfd.h or
- libcoff.h, from comments in the source. See also doc.str.
- Output lines generally come from comment lines starting with a dot,
- or from keywords like SYNOPSIS. Output switches to bfd-in2.h at the
- end of each comment. Use INTERNAL* to output to libbfd.h.
-
- EXTERNAL: output to bfd-in2.h, nothing to docs
- INTERNAL: output to libbfd.h, nothing to docs
- CODE_FRAGMENT: output to header and docs
- FUNCTION: output to bfd-in2.h and docs
- INTERNAL_FUNCTION: output to libbfd.h and docs
- DEFINITION: alias for FUNCTION, but generally doesn't have SYNOPSIS,
- used for structs and other random code
- INTERNAL_DEFINITION: as above, but output to libbfd.h and docs
- ENUM* outputs to bfd-in2.h, libbfd.h and docs.
19990502 sourceware import
1999-05-03 15:29:11 +08:00
: SYNOPSIS
skip_past_newline
get_stuff_in_command
Generated docs and include files bfd/doc/chew.c extracts documentation from source code comments annotated with keywords, and generates much of bfd.h and libbfd.h from those same comments. The docs have suffered from people (me too) adding things like CODE_FRAGMENT to the source to put code into bfd.h without realising that CODE_FRAGMENT also puts @example around said code into the docs. So we have random senseless things in the docs. This patch fixes that problem (well, the senseless things from CODE_FRAGMENT), moves most of the code out of bfd-in.h, and improves a few chew.c features. libbfd.h now automatically gets ATTRIBUTE_HIDDEN prototypes, and indentation in bfd.h and libbfd.h is better.
2023-04-30 19:12:30 +08:00
translatecomments
strip_trailing_newlines
remchar
" ATTRIBUTE_HIDDEN" internalmode @ catstrif
";\n\n" catstr
19990502 sourceware import
1999-05-03 15:29:11 +08:00
indent
maybecatstr
;
Generated docs and include files bfd/doc/chew.c extracts documentation from source code comments annotated with keywords, and generates much of bfd.h and libbfd.h from those same comments. The docs have suffered from people (me too) adding things like CODE_FRAGMENT to the source to put code into bfd.h without realising that CODE_FRAGMENT also puts @example around said code into the docs. So we have random senseless things in the docs. This patch fixes that problem (well, the senseless things from CODE_FRAGMENT), moves most of the code out of bfd-in.h, and improves a few chew.c features. libbfd.h now automatically gets ATTRIBUTE_HIDDEN prototypes, and indentation in bfd.h and libbfd.h is better.
2023-04-30 19:12:30 +08:00
- Ignore stuff that is for the docs. Output lines starting with dots.
19990502 sourceware import
1999-05-03 15:29:11 +08:00
: ignore
skip_past_newline
get_stuff_in_command
outputdots
maybecatstr
;
: CODE_FRAGMENT
ignore ;
Generated docs and include files bfd/doc/chew.c extracts documentation from source code comments annotated with keywords, and generates much of bfd.h and libbfd.h from those same comments. The docs have suffered from people (me too) adding things like CODE_FRAGMENT to the source to put code into bfd.h without realising that CODE_FRAGMENT also puts @example around said code into the docs. So we have random senseless things in the docs. This patch fixes that problem (well, the senseless things from CODE_FRAGMENT), moves most of the code out of bfd-in.h, and improves a few chew.c features. libbfd.h now automatically gets ATTRIBUTE_HIDDEN prototypes, and indentation in bfd.h and libbfd.h is better.
2023-04-30 19:12:30 +08:00
- Output goes to bfd-in2.h
: EXTERNAL
Change internalmode to be an intrinsic variable Currently, internalmode is a special word to set an internal state variable. Because this series adds variables anyway, change this to be a variable instead. I saw some commits in the history that made sure that chew did not leak memory, so I put some extra effort into trying to handle this for variables as well. 2023-02-07 Tom Tromey <tom@tromey.com> * doc/proto.str (external, internal, ifinternal, ENUMEQ, ENUMDOC): Update. * doc/chew.c (internalmode): Remove. (add_intrinsic_variable): New function. (main): Add internalmode as intrinsic. (internal_mode): Remove global. (maybecatstr): Update. (free_words): Free variables.
2023-02-08 03:14:54 +08:00
0 internalmode ! ignore ;
19990502 sourceware import
1999-05-03 15:29:11 +08:00
Generated docs and include files bfd/doc/chew.c extracts documentation from source code comments annotated with keywords, and generates much of bfd.h and libbfd.h from those same comments. The docs have suffered from people (me too) adding things like CODE_FRAGMENT to the source to put code into bfd.h without realising that CODE_FRAGMENT also puts @example around said code into the docs. So we have random senseless things in the docs. This patch fixes that problem (well, the senseless things from CODE_FRAGMENT), moves most of the code out of bfd-in.h, and improves a few chew.c features. libbfd.h now automatically gets ATTRIBUTE_HIDDEN prototypes, and indentation in bfd.h and libbfd.h is better.
2023-04-30 19:12:30 +08:00
- Output goes to libbfd.h/libcoff.h
: INTERNAL
Change internalmode to be an intrinsic variable Currently, internalmode is a special word to set an internal state variable. Because this series adds variables anyway, change this to be a variable instead. I saw some commits in the history that made sure that chew did not leak memory, so I put some extra effort into trying to handle this for variables as well. 2023-02-07 Tom Tromey <tom@tromey.com> * doc/proto.str (external, internal, ifinternal, ENUMEQ, ENUMDOC): Update. * doc/chew.c (internalmode): Remove. (add_intrinsic_variable): New function. (main): Add internalmode as intrinsic. (internal_mode): Remove global. (maybecatstr): Update. (free_words): Free variables.
2023-02-08 03:14:54 +08:00
1 internalmode ! ignore ;
19990502 sourceware import
1999-05-03 15:29:11 +08:00
- input stack { a b } output b if internal, a if external
: ifinternal
Change internalmode to be an intrinsic variable Currently, internalmode is a special word to set an internal state variable. Because this series adds variables anyway, change this to be a variable instead. I saw some commits in the history that made sure that chew did not leak memory, so I put some extra effort into trying to handle this for variables as well. 2023-02-07 Tom Tromey <tom@tromey.com> * doc/proto.str (external, internal, ifinternal, ENUMEQ, ENUMDOC): Update. * doc/chew.c (internalmode): Remove. (add_intrinsic_variable): New function. (main): Add internalmode as intrinsic. (internal_mode): Remove global. (maybecatstr): Update. (free_words): Free variables.
2023-02-08 03:14:54 +08:00
"" swap 1 internalmode ! maybecatstr
19990502 sourceware import
1999-05-03 15:29:11 +08:00
swap
Change internalmode to be an intrinsic variable Currently, internalmode is a special word to set an internal state variable. Because this series adds variables anyway, change this to be a variable instead. I saw some commits in the history that made sure that chew did not leak memory, so I put some extra effort into trying to handle this for variables as well. 2023-02-07 Tom Tromey <tom@tromey.com> * doc/proto.str (external, internal, ifinternal, ENUMEQ, ENUMDOC): Update. * doc/chew.c (internalmode): Remove. (add_intrinsic_variable): New function. (main): Add internalmode as intrinsic. (internal_mode): Remove global. (maybecatstr): Update. (free_words): Free variables.
2023-02-08 03:14:54 +08:00
"" swap 0 internalmode ! maybecatstr
19990502 sourceware import
1999-05-03 15:29:11 +08:00
catstr
;
- Put note in output string, regardless of internal mode.
: COMMENT
skip_past_newline
get_stuff_in_command
translatecomments
catstr
;
- SENUM enum-type-name
- ENUM enum-name
- ENUMX addl-enum-name
- ENUMDOC doc for preceding enums
- ENDSENUM max-enum-name
: make_enum_header
dup
"enum " swap catstr
bfd-in2.h BFD_RELOC_* comments I noticed the regenerated BFD_RELOC_MICROBLAZE_32_NONE comment didn't match that committed to bfd-in2.h, and was just going to regen bfd-in2.h but then decided to do something about the silly formatting of these comments in bfd-in2.h. eg. the BFD_RELOC_MICROBLAZE_32_NONE comment: -/* This is a 32 bit reloc that stores the 32 bit pc relative -value in two words (with an imm instruction).No relocation is -done here - only used for relaxing */ + /* This is a 32 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). No relocation is done here - + only used for relaxing. */ BFD_RELOC_MICROBLAZE_32_NONE, You'll notice how the second and third line of the original comment aren't indented properly relative to the first line, and the whole comment needs to be indented to match the code. I've also edited reloc.c ENUMDOC paragraphs. Some of these had excess indentation, presumably in an attempt to properly indent bfd-in2.h comments but that fails due to chew.c removing leading whitespace early by skip_white_and_stars. COMMENT was used in reloc.c to add extra blank lines in bfd-in2.h. I've removed them too as I don't think they add anything to readability of that file. (Perhaps more usefully, they also add blank lines to libbfd.h separating relocs for one target from others, but this isn't done consistently.) * doc/chew.c (drop, idrop): Move earlier. (strip_trailing_newlines): Check index before accessing array, not after. (wrap_comment): New function. (main): Add "wrap_comment" intrinsic. * doc/proto.str (ENUMDOC): Use wrap_comment. (make_enum_header, ENDSENUM): Put start and end braces on separate lines. * reloc.c: Remove uses of COMMENT and edit ENUMDOC paragraphs. * libbfd.h: Regenerate. * bfd-in2.h: Regenerate.
2023-10-21 15:24:59 +08:00
"\n{\n" catstr
19990502 sourceware import
1999-05-03 15:29:11 +08:00
swap " _dummy_first_" swap catstr catstr
",\n" catstr
;
: make_string_table_header
dup
"#ifdef _BFD_MAKE_TABLE_" swap catstr swap
"\n\nstatic const char *const " swap catstr catstr
"_names[] = { \"@@uninitialized@@\",\n" catstr
;
: SENUM
skip_past_newline
copy_past_newline
remchar
dup
make_enum_header
swap
make_string_table_header
ifinternal
catstr
get_stuff_in_command catstr
translatecomments ;
: ENDSENUM
skip_past_newline
copy_past_newline strip_trailing_newlines
dup
bfd-in2.h BFD_RELOC_* comments I noticed the regenerated BFD_RELOC_MICROBLAZE_32_NONE comment didn't match that committed to bfd-in2.h, and was just going to regen bfd-in2.h but then decided to do something about the silly formatting of these comments in bfd-in2.h. eg. the BFD_RELOC_MICROBLAZE_32_NONE comment: -/* This is a 32 bit reloc that stores the 32 bit pc relative -value in two words (with an imm instruction).No relocation is -done here - only used for relaxing */ + /* This is a 32 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). No relocation is done here - + only used for relaxing. */ BFD_RELOC_MICROBLAZE_32_NONE, You'll notice how the second and third line of the original comment aren't indented properly relative to the first line, and the whole comment needs to be indented to match the code. I've also edited reloc.c ENUMDOC paragraphs. Some of these had excess indentation, presumably in an attempt to properly indent bfd-in2.h comments but that fails due to chew.c removing leading whitespace early by skip_white_and_stars. COMMENT was used in reloc.c to add extra blank lines in bfd-in2.h. I've removed them too as I don't think they add anything to readability of that file. (Perhaps more usefully, they also add blank lines to libbfd.h separating relocs for one target from others, but this isn't done consistently.) * doc/chew.c (drop, idrop): Move earlier. (strip_trailing_newlines): Check index before accessing array, not after. (wrap_comment): New function. (main): Add "wrap_comment" intrinsic. * doc/proto.str (ENUMDOC): Use wrap_comment. (make_enum_header, ENDSENUM): Put start and end braces on separate lines. * reloc.c: Remove uses of COMMENT and edit ENUMDOC paragraphs. * libbfd.h: Regenerate. * bfd-in2.h: Regenerate.
2023-10-21 15:24:59 +08:00
" " swap catstr "\n};\n" catstr swap
19990502 sourceware import
1999-05-03 15:29:11 +08:00
" \"@@overflow: " swap catstr "@@\",\n};\n#endif\n\n" catstr
ifinternal
catstr
;
: make_enumerator
" " swap catstr
",\n" catstr
;
: make_enumerator_string
" \"" swap catstr
"\",\n" catstr
;
: ENUM
skip_past_newline
copy_past_newline
remchar
dup
make_enumerator
swap
make_enumerator_string
ifinternal
;
: ENUMX ENUM catstr ;
: ENUMEQ
skip_past_newline
"#define "
copy_past_newline remchar
catstr
" "
catstr
copy_past_newline
catstr
Change internalmode to be an intrinsic variable Currently, internalmode is a special word to set an internal state variable. Because this series adds variables anyway, change this to be a variable instead. I saw some commits in the history that made sure that chew did not leak memory, so I put some extra effort into trying to handle this for variables as well. 2023-02-07 Tom Tromey <tom@tromey.com> * doc/proto.str (external, internal, ifinternal, ENUMEQ, ENUMDOC): Update. * doc/chew.c (internalmode): Remove. (add_intrinsic_variable): New function. (main): Add internalmode as intrinsic. (internal_mode): Remove global. (maybecatstr): Update. (free_words): Free variables.
2023-02-08 03:14:54 +08:00
"" swap 0 internalmode ! maybecatstr
19990502 sourceware import
1999-05-03 15:29:11 +08:00
;
: ENUMEQX ENUMEQ catstr ;
: ENUMDOC
skip_past_newline
get_stuff_in_command
strip_trailing_newlines
bfd-in2.h BFD_RELOC_* comments I noticed the regenerated BFD_RELOC_MICROBLAZE_32_NONE comment didn't match that committed to bfd-in2.h, and was just going to regen bfd-in2.h but then decided to do something about the silly formatting of these comments in bfd-in2.h. eg. the BFD_RELOC_MICROBLAZE_32_NONE comment: -/* This is a 32 bit reloc that stores the 32 bit pc relative -value in two words (with an imm instruction).No relocation is -done here - only used for relaxing */ + /* This is a 32 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). No relocation is done here - + only used for relaxing. */ BFD_RELOC_MICROBLAZE_32_NONE, You'll notice how the second and third line of the original comment aren't indented properly relative to the first line, and the whole comment needs to be indented to match the code. I've also edited reloc.c ENUMDOC paragraphs. Some of these had excess indentation, presumably in an attempt to properly indent bfd-in2.h comments but that fails due to chew.c removing leading whitespace early by skip_white_and_stars. COMMENT was used in reloc.c to add extra blank lines in bfd-in2.h. I've removed them too as I don't think they add anything to readability of that file. (Perhaps more usefully, they also add blank lines to libbfd.h separating relocs for one target from others, but this isn't done consistently.) * doc/chew.c (drop, idrop): Move earlier. (strip_trailing_newlines): Check index before accessing array, not after. (wrap_comment): New function. (main): Add "wrap_comment" intrinsic. * doc/proto.str (ENUMDOC): Use wrap_comment. (make_enum_header, ENDSENUM): Put start and end braces on separate lines. * reloc.c: Remove uses of COMMENT and edit ENUMDOC paragraphs. * libbfd.h: Regenerate. * bfd-in2.h: Regenerate.
2023-10-21 15:24:59 +08:00
" " wrap_comment
"\n" swap catstr "\n" catstr
19990502 sourceware import
1999-05-03 15:29:11 +08:00
- discard it if we're doing internal mode
Change internalmode to be an intrinsic variable Currently, internalmode is a special word to set an internal state variable. Because this series adds variables anyway, change this to be a variable instead. I saw some commits in the history that made sure that chew did not leak memory, so I put some extra effort into trying to handle this for variables as well. 2023-02-07 Tom Tromey <tom@tromey.com> * doc/proto.str (external, internal, ifinternal, ENUMEQ, ENUMDOC): Update. * doc/chew.c (internalmode): Remove. (add_intrinsic_variable): New function. (main): Add internalmode as intrinsic. (internal_mode): Remove global. (maybecatstr): Update. (free_words): Free variables.
2023-02-08 03:14:54 +08:00
"" swap 0 internalmode ! maybecatstr
19990502 sourceware import
1999-05-03 15:29:11 +08:00
swap
catstr catstr
;
: SECTION ignore ;
: SUBSECTION ignore ;
: SUBSUBSECTION ignore ;
: INODE ignore ;
Generated docs and include files bfd/doc/chew.c extracts documentation from source code comments annotated with keywords, and generates much of bfd.h and libbfd.h from those same comments. The docs have suffered from people (me too) adding things like CODE_FRAGMENT to the source to put code into bfd.h without realising that CODE_FRAGMENT also puts @example around said code into the docs. So we have random senseless things in the docs. This patch fixes that problem (well, the senseless things from CODE_FRAGMENT), moves most of the code out of bfd-in.h, and improves a few chew.c features. libbfd.h now automatically gets ATTRIBUTE_HIDDEN prototypes, and indentation in bfd.h and libbfd.h is better.
2023-04-30 19:12:30 +08:00
: DESCRIPTION ignore ;
PR31314, chew crashing on use of uninitialized value The "drop" call in wrap_comment already increments pc. Defining DOCDD in proto.str is a warning fix. PR 31314 * chew.c (wrap_comment): Don't increment pc. * proto.str (DOCDD): Define.
2024-01-30 07:08:56 +08:00
: DOCDD ignore ;
Generated docs and include files bfd/doc/chew.c extracts documentation from source code comments annotated with keywords, and generates much of bfd.h and libbfd.h from those same comments. The docs have suffered from people (me too) adding things like CODE_FRAGMENT to the source to put code into bfd.h without realising that CODE_FRAGMENT also puts @example around said code into the docs. So we have random senseless things in the docs. This patch fixes that problem (well, the senseless things from CODE_FRAGMENT), moves most of the code out of bfd-in.h, and improves a few chew.c features. libbfd.h now automatically gets ATTRIBUTE_HIDDEN prototypes, and indentation in bfd.h and libbfd.h is better.
2023-04-30 19:12:30 +08:00
: ENDDD EXTERNAL ;
: FUNCTION EXTERNAL ;
: INTERNAL_FUNCTION INTERNAL ;
: DEFINITION EXTERNAL ;
: INTERNAL_DEFINITION INTERNAL ;
Reference in New Issue Copy Permalink