Collect files and indexes in API Documentation Set #3486
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
With this change, I have extracted the parsing of each API set into a sub-pipeline. This means that we can now parse multiple sets of API Documentation instead of just the first. However, it doesn't work quite yet. As the files are still added onto the ProjectDescriptor. This change merely changes the process, but shouldn't affect the application as long as the guard that only 1 API Set may be present is in place. In a subsequent change, we will be modifying the parsing logic itself to work more with the Documentation Set descriptors instead of the ProjectDescriptor
…r-documentation-set
While reviewing, I noticed that a) I had added a method to the ApiSetDescriptor that I really do not need anymore, and b) the Parser Payload is no longer really used. I have now replaced the Parser Payload with its parent (the normal Payload) and found that the stage to transform the regular Payload to the Parser payload was unnecessary; so I cut it out to simplify the process.
During the parsing phase, I had used ApiSpecifications instead of the ApiSetDescriptor because I believed the ApiSetDescriptors were created later. I found that the ApiSetDescriptors are built in the InitializeBuilderFromConfig stage, meaning I can use them in the parse stages. This will simplify the change where files and indexes are directly set in the ApiSetDescriptor instead of on the ProjectDescriptor because the ParseFiles stage now has direct access to the ApiSetDescriptor
In this change, I have changed the way the ParseFiles stage works by having it directly push the parsed files into the ApiSetDescriptor instead of the ProjectDescriptor. Since the ProjectDescriptor's Files and Indexes collections are proxies for the first ApiSet at the moment, nothing changes in the way phpDocumentor works. This change is again moving forward with the plan to remove the getFiles and getIndexes from the ProjectDescriptor. As soon as that is gone, we have successfully decoupled documentation sets from the main project and be able to support multiple of them.
jaapio
reviewed
Mar 22, 2023
| $builder->usingApiSpecification($apiConfig); | ||
| $builder->usingDefaultPackageName($apiConfig['default-package-name'] ?? ''); | ||
|
|
||
| // TODO: The setVisibility call should purge the cache if it differs; but once we are here, cache has already |
There was a problem hiding this comment.
I think when we move the filtering into the compiler... we do not need to invalidate the cache... filtering should just transform the output of the parser stage, it will not harm to have a pure parser output. As the filters are already running over the descriptors.
There was a problem hiding this comment.
IIRC, the visibility part was originally in the parser instead of the compiler so that 'unauthorized' code would not end up in the cache or in the ast dump file. This as a means of protecting IP even though things could be distributed. I am doubting whether it is a real thing, but that was the original reason :)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Important: this PR is based on the work in #3485, and that should be reviewed and merged first
In this change, I have changed the way the ParseFiles stage works by
having it directly push the parsed files into the ApiSetDescriptor
instead of the ProjectDescriptor.
Since the ProjectDescriptor's Files and Indexes collections are proxies
for the first ApiSet at the moment, nothing changes in the way
phpDocumentor works. This change is again moving forward with the plan
to remove the getFiles and getIndexes from the ProjectDescriptor. As
soon as that is gone, we have successfully decoupled documentation sets
from the main project and be able to support multiple of them.