Branch: refs/heads/blead
Home: https://github.com/Perl/perl5
Commit: 5295a7116512d54524d09df4357af409481e801e
https://github.com/Perl/perl5/commit/5295a7116512d54524d09df4357af409481e801e
Author: Karl Williamson
Date: 2024-06-16 (Sun, 16 Jun 2024)
Changed paths:
M autodoc.pl
Log Message:
---
autodoc.pl: White-space only
Wrap lines to fit in an 80 column terminal
Commit: 90be1ac7c0cbf05700eee2deb76b88b535b546e7
https://github.com/Perl/perl5/commit/90be1ac7c0cbf05700eee2deb76b88b535b546e7
Author: Karl Williamson
Date: 2024-06-16 (Sun, 16 Jun 2024)
Changed paths:
M autodoc.pl
Log Message:
---
autodoc: improve internal uniformity of entries
Originally, each entry was for a single function or macro, etc. Then
the ability to group similar items in a single entry was shoe-horned in,
with the extra ones in a group being a subsidiary data structure with
most of the same elements. But it is easier to code new things based on
a uniform structure with all items the same. That's what this commit
does.
The first item in a group is added to the array of all the items as the
0th element.
This had already been done in one subroutine because it made for easier
handling; this commit moves that to much earlier in the process.
Commit: da698f8f246dc59f2158f7c56d83a85d126fbee6
https://github.com/Perl/perl5/commit/da698f8f246dc59f2158f7c56d83a85d126fbee6
Author: Karl Williamson
Date: 2024-06-16 (Sun, 16 Jun 2024)
Changed paths:
M autodoc.pl
Log Message:
---
autodoc: Extract code into a function
This is in preparation for it being called from a second place.
Commit: 8264ee4c88a0b12fa191cb5b2c0ff3bd1e7550e9
https://github.com/Perl/perl5/commit/8264ee4c88a0b12fa191cb5b2c0ff3bd1e7550e9
Author: Karl Williamson
Date: 2024-06-16 (Sun, 16 Jun 2024)
Changed paths:
M autodoc.pl
Log Message:
---
autodoc: Extract code into function
This is in preparation for it to be called from more places
Commit: e09e48074f0717ae8e92ae9dea0ca67361c100d9
https://github.com/Perl/perl5/commit/e09e48074f0717ae8e92ae9dea0ca67361c100d9
Author: Karl Williamson
Date: 2024-06-16 (Sun, 16 Jun 2024)
Changed paths:
M autodoc.pl
Log Message:
---
autodoc: Add missing /x on pattern
The issue this was supposed to be protecting against had never come up
Commit: e460de7d043e47f7589331516bfb9dda0a2b87b5
https://github.com/Perl/perl5/commit/e460de7d043e47f7589331516bfb9dda0a2b87b5
Author: Karl Williamson
Date: 2024-06-16 (Sun, 16 Jun 2024)
Changed paths:
M autodoc.pl
Log Message:
---
autodoc: Clarifications
This changes some comments and white space, and reverses the logic of
some conditionals to make clearer what is being done, especially with
future commits
Commit: ef302588bff6e9cead3506a3d6117d3edd1ca9e0
https://github.com/Perl/perl5/commit/ef302588bff6e9cead3506a3d6117d3edd1ca9e0
Author: Karl Williamson
Date: 2024-06-16 (Sun, 16 Jun 2024)
Changed paths:
M autodoc.pl
M embed.fnc
Log Message:
---
autodoc: Add apidoc_defn directive
perlapi and perlintern document a variety of constructs. Function
prototypes are declared in embed.fnc and used to generate header files
that the compiler sees, for example, to declare function signatures
without having to worry that a function call will be encountered during
compilation prior to its definition. The compiler likely notes any
discrepancies.
Macros don't have that kind of checking, beyond having the correct
number of parameters. We have added some further macros that can be
applied to individual parameters in the main macro's definition to make
sure the parameter is a pointer when it should be, and vice versa. But
lots of possible issues are uncaught.
We also can specify our expected types of each parameter in embed.fnc
like we do for functions, and additionally in apidoc lines. But, those
can be wrong without it being apparent.
To lessen the chances of being wrong, it would be advantageous to place
the declaration of the macro's signature adjacent to its actual
definition in the code. Discrepancies are easily noted.
But this conflicts with combining many variants of a function into the
same api entry. Some variants will be functions, and their definitions
will likely be in .c files, while others will be macros that merely wrap
the function call. These will necessarily be in .h files.
This commit is a solution. The new construct 'apidoc_defn' is created.
This is to be placed adjacent to the macro's definition, documenting
there how we expect it to be called. But it only contains the macro's
signature. Somewhere else in the source will be a regular apidoc (or
apidoc_item) line without any signature information attached to it.
That line will put the information from the apidoc_defn no matter where
in the source it is locate
