summaryrefslogtreecommitdiff
path: root/autodoc.pl
Commit message (Collapse)AuthorAgeFilesLines
* autodoc.pl: strftime format functions can use short namesKarl Williamson2023-05-031-1/+3
| | | | | It was saying you had to use the Perl_foo(aTHX_ ...) form, which isn't true.
* regen/embed.pl - switch to using HeaderParser for code generation and etc.Yves Orton2022-12-241-4/+6
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | HeaderParser was designed to replace the old grouping code in embed.pl and regen/embed_lib.pl, which is used to generate embed.h and proto.h and embedvar.h It can handle "elif" in embed.fnc, and produces more consistently structured and formatted and readable output than the old code. It also has much better logic to dedupe expressions. Adding or changing a constraint in embed.fnc should no longer have any "action at a distance" effects on the output for other functions which were not changed or obviously affected by the change. The old code assumed that sorting the constraints applying to a given function definition was acceptable, with the result that "elif" was impossible to support properly, and creating the problem that adding a new constraint which sorted into a different position could change a large amount of the output, making it hard to verify that the change was correct. The new logic should, once the initial normalization is applied, ensure that any further changes are minimal. This patch also includes a new tool regen/normalize_embed.pl which will be run by make regen, which consistently formats embed.fnc itself, which should make maintaining the file easier, especially during code splits and reorgs. Function definitions can be lifted out, moved to the end, with new constraints, and the `make regen` will put it all back into the correct place and order. A number of tools and tests which use embed_lib.pl to load embed.fnc data have necessarily been changed to use the new HeaderParser based logic.
* Remove ~~ from autodoc.plPhilippe Bruhat (BooK)2022-09-231-2/+3
|
* perlapi: Sort X<> tagsKarl Williamson2022-07-021-1/+1
| | | | | This is just to minimize difference listings between versions of this file, as these don't actually get displayed in the pod.
* Sort perlapi, perlintern betterKarl Williamson2022-07-011-5/+60
| | | | | | | | | | | | | | | | This changes the dictionary sort to be closer to a standard dictionary sort. Underscores and digits collate to after all other characters, and sequences of digits collate numerically even if one sequence is shorter than the other. Unless a tie breaker is needed, non-trailing underscores and digits are ignored. The result is I8 comes before I16; IV before I8; __ASSERT_ before ASSUME, etc. The results look more intuitive to me, but could be tweaked if advisable.
* perlapi: Slight wording changeKarl Williamson2022-07-011-1/+1
|
* perlapi,intern: Split undcmntd items into 3 classesKarl Williamson2022-07-011-46/+118
| | | | | | | | | | | | | | | | | | Those classes being: plain, experimental, and deprecated. Suppose I'm an XS writer and I've found an undocumented function or macro that I'd like to use. Should I use it? Certainly not if it's deprecated. Pretty iffy if it's experimental, but maybe worth a try to ask p5p about it. Less iffy if just plain, but the pod says to ask p5p to be sure. These distinctions do matter some, and so this commit makes them. Prior to it, perlapi experimental and deprecated elements weren't mentioned anywhere, as if they had dropped off the face of the earth.
* perlapi: Ensure ref-only items have X<>Karl Williamson2022-07-011-4/+14
| | | | | | | | | Some minor API elements, such as flag values, in perlapi are mentioned only in passing in the pod of some encompassing element. This commit makes sure those minor elements have a X<> pod element generated for them in the appropriate place. This makes sure that other code that, say, indexes the API knows whereabouts to link, etc. to.
* autodoc.pl: Fix spelling error in inline commentJames E Keenan2022-06-271-1/+1
|
* autodoc.pl: s/guts/intern/ (mostly)Karl Williamson2022-06-171-4/+4
| | | | | The terms 'guts' and 'intern' are conflated in this file prior to this commit. perlguts and perlintern are separate entties.
* Add '#' flag for autodoc entriesKarl Williamson2022-06-171-1/+7
| | | | | This indicates the symbol is accessed via #ifdef and is not a function or a macro with a returned value
* Change autodoc flagKarl Williamson2022-06-141-6/+6
| | | | | | This should be being used only in core, as its only use is for autodoc. Change the flag name to be more mnemonic, freeing up its current name for another use.
* perlapi: Link to perlguts for more elementsKarl Williamson2022-05-171-0/+7
| | | | | | A bunch of API (and perlintern) elements are actually documented in perlguts. Add links to many of them. This entails a new section in perlapi for Perl formats
* perlapi: Slightly change names of two sectionsKarl Williamson2022-05-171-2/+2
| | | | | These include more than 'configuration values', so drop that from the title
* autodoc.pl: Properly handle a single columnKarl Williamson2022-05-151-1/+5
| | | | | | | | | | The program attempts to make a table of some of the output for compactness. But if there is room for only a single column, it was using the number of rows that it calculated were necessary should two columns have worked; hence the output was only displaying the first half of the rows in perlintern.pod. What is needed is to do the loop a partial final iteration, just enough to calculate the number of rows for that final column.
* autodoc.pl: Fix line wrapKarl Williamson2022-05-121-1/+1
| | | | It was failing to account for the 1 column indent for verbatim lines
* autodoc.pl: White-space onlyKarl Williamson2022-05-121-3/+3
| | | | Indent for clarification
* autodoc.pl: deb.c default section is debuggingKarl Williamson2022-05-121-0/+1
|
* perlapi: Don't indent table of undocumentedsKarl Williamson2022-05-111-7/+5
| | | | | | There's really no need to do this esthetically, and it gets us close to fitting an extra column in a standard terminal width to shorten the table. Future commits will gain that column.
* perlapi: Explicity specify =over indentKarl Williamson2022-05-111-6/+7
| | | | So it can be easily changed
* perlapi: Include threads in embedding section nameKarl Williamson2022-05-111-1/+1
| | | | | This section of perlapi currently includes thread-related functions, but that wasn't clear from the section heading.
* perlapi: Change name of 'formats' sectionKarl Williamson2022-05-111-18/+18
| | | | | | This section is about things that are used in I/O formats like sprintf(%foo). This would be confusable with Perl formats used in reports.
* perlapi: Rename GV sectionKarl Williamson2022-05-091-1/+1
| | | | | In practice, like in perlguts, GVs and Stashes are lumped together, and some API functions deal with both. So rename the section they go in.
* perlapi: Rename COP sectionKarl Williamson2022-05-091-1/+1
| | | | | Previously it was just named "COP Hint Hashes", but it includes more than that.
* perlapi: Combine the two optree sectionsKarl Williamson2022-05-091-2/+7
| | | | | One was for construction; the other for manipulation. In practice the boundary is blurry, so just make them one plain optree section
* perlapi: default section for sv.[ch] is SVKarl Williamson2022-05-081-0/+2
|
* autodoc: Resort two listsKarl Williamson2022-05-071-2/+2
| | | | A name earlier had changed, so was now out of order
* autodoc: Rmv obsolete lineKarl Williamson2022-05-071-1/+0
| | | | | | This defines a variable if not defined, and dates from earlier logic, and wasn't removed when that logic changed. This line hid bugs that the next line is supposed to catch.
* autodoc: sv_inline.h fcns are going to be for SVKarl Williamson2022-05-071-0/+1
|
* perlapi,perlintern: Add tainting sectionKarl Williamson2022-05-061-0/+3
| | | | | | Tainting is so specialized that things dealing with it are better gathered together in one place. This commit moves the existing docs for such API into the new section
* autodoc.pl: Rmv redundant textKarl Williamson2022-05-031-12/+46
| | | | | | | | When different functions are grouped together in a single entry, some or all of them may be deprecated or experimental. Prior to this commit each such was listed individually as a separate paragraph. It is shorter to say "All forms" if all are of the same ilk, or list just the individual ones in a single sentence, otherwise.
* autodoc.pl: Allow 'x' flag in apidoc_item entriesKarl Williamson2022-05-031-1/+1
| | | | | The only flags allowed are those affecting the display in perlapi and perlintern. The 'x' flag previously omitted, fits this.
* autodoc: Don't require space after =apidoc_itemKarl Williamson2022-05-031-2/+3
| | | | The flags column is optional, and so no space is needed to delimit it.
* autodoc.pl: Include thread context in arg calculationKarl Williamson2022-05-031-2/+6
| | | | | | | | | | When several different functions are grouped together into one entry, only the signature of the first one is output provided that all have the same signature (except for the function name). Until this commit, whether or not there was a hidden thread context parameter was not considered in this calculation. This could lead to confusion.
* autodoc.pl: Clarify commentKarl Williamson2022-05-031-1/+1
|
* autodoc.pl: perlxs items default to XS sectionKarl Williamson2022-05-021-0/+1
|
* autodoc.pl: A source is perlxs.podKarl Williamson2022-05-021-5/+8
| | | | | | | | | | | | | | This was meant to be looked at, but wasn't. It's skipping cpan, dist, and ext, which it really should be, because we don't have much control over those. The comments indicated it expected to get generated files from lib/ instead, but those wouldn't be in MANIFEST, so weren't getting looked at. And it's not a good idea to look for them anyway, as one could get relicts. Instead create an exception list of pods that could have API elements that are documented. The only current file on that list is what becomes lib/perlxs.pod
* make autodoc.pl and makedef.pl understand the I embed.fnc flagTomasz Konojacki2022-02-041-1/+1
| | | | | It's needed in case a publicly visible PERL_STATIC_FORCE_INLINE function is added.
* autodoc.pl: 'G' is a legitimate embed.fnc flagKarl Williamson2021-04-141-1/+1
|
* autodoc.pl: Adjust max permissible line lengthKarl Williamson2020-12-141-3/+3
| | | | perldoc takes up 4 column indent, not 7.
* Account for 'less' reserving an extra columnKarl Williamson2020-11-301-2/+2
| | | | | | | | | | | | | | | | | | | | After decades of stability, the 'less' pager project decided to claim an extra column for its own use when called with certain common options. This commit changes some of the auto-generating tools to wrap one column earlier to compensate, and changes podcheck to also whine on wide verbatim text one column less. But it changes the podcheck data base to grandfather-in all the many existing places that exceed that amount. That means only changes made to pods after this commit will be held to the stricter value. Of course, what this means is those pods will wrap or truncate in these places on an 80 column window, making them harder to read, when used with 'less' and when it is called with the options that reserve those two columns. Patches welcome. I haven't seen the wrapping problem with perldoc, and haven't investigated much.
* perlapi: Remove per-thread section; move to real scnsKarl Williamson2020-11-251-2/+0
| | | | | Instead of having a grab bag section of all interpreter variables, move their documentation to the section that they actually fit under.
* perlapi/perlintern: Better sort the SEE ALSO scnKarl Williamson2020-11-071-4/+7
|
* perlapi: Split section Display and DumpKarl Williamson2020-11-061-3/+5
| | | | into Debugging and Display sections
* autodoc.pl: A hash needs to have no keys to be emptyKarl Williamson2020-11-061-2/+1
|
* autodoc.pl: Specify scn for single-purpose filesKarl Williamson2020-11-061-4/+60
| | | | | | | | Many of the files in perl are for one thing only, and hence their embedded documentation will be for that one thing. By creating a hash here of them, those files don't have to worry about what section that documentation goes under, and so it can be completely changed without affecting them.
* Revert and fix "autodoc.pl: Don't recalculate value"Karl Williamson2020-11-061-3/+7
| | | | | | | | This reverts commit 0213d97dcda976f02ce257031d969e7964ecc545, and fixes it up. That commit failed to account for that there were extra components needed in the calculation
* autodoc.pl: Enhance apidoc_section featureKarl Williamson2020-11-061-8/+19
| | | | | | | | | | | This feature allows documentation destined for perlapi or perlintern to be split into sections of related functions, no matter where the documentation source is. Prior to this commit the line had to contain the exact text of the title of the section. Now it can be a $variable name that autodoc.pl expands to the title. It still has to be an exact match for the variable in autodoc, but now, the expanded text can be changed in autodoc alone, without other files needing to be updated at the same time.
* perlapi: Add a link at the beginning to the UndocumentedsKarl Williamson2020-11-051-3/+8
|
* autodoc.pl: Rename a few variables for consistencyKarl Williamson2020-11-051-9/+9
|
View Lorry Controller Status