Streamline getDocumentationTryGhc

[Anton-Latukha]

The main agenda there is to provide argument documentation in a form that is neat for further processing. As to provide the documentation as maps from the name to documentation. Which would allow to properly shipping the function argument show work.

During that, improving on getDocumentation{,s}TryGhc code paths:

• Introducing initTypecheckEnv to abstract type checking environment initialization between several modes. (It abstracts code that is currently in mainline, further improvements there seem to be possible but they are not the scope of this PR, but are considered future changes).

• Introducing the getDocsNonInteractive', a function that was used/requested in the source code but not abstracted - a function that is analog to GHCs getDocs but modifies it to work in the non-interactive form. Gets used as an abstraction to open module interfaces to retrieve documentation.

• Introducing getDocsNonInteractive - a function to get the documentation about a Name from a module interface.

• Updating getDocsBatch - to share abstractions with getDocsNonInteractive. These updates also make available possibilities of further optimizations as in getDocsBatch for bulk processing #2371.

• getDocumentationTryGhc (single):

  • as being the current main code path, now uses equivalent process (getDocsNonInteractive), and as so - no longer depends on getDocumentationsTryGhc (plural).
  • because no longer uses getDocumentationsTryGhc (plural) - getDocumentationTryGhc (single) no longer needs to pretend element is a singleton to send it to getDocumentationsTryGhc (plural) to retrieve a head

• getDocumentationsTryGhc (plural):

  • No longer used. The current patch just shows that this code path is not used in reality, actively doing that also allows working on the batch retrieval if it is found beneficial.

  • Instead of IO [SpanDoc] (& matching Names on [] indexes) - returns proper Map Name SpanDoc type.

  • There was use of Lazy Map in the code, which seemed to imply use/process all elements, considered it is enough obvious to ensure those are Strict Maps, that is a minor thing and can roll it back upon request.

• This PR is a part of the effort to provision argument documentation into UI. All mentioned above functions are used to pass the argument documentation further into the code. GHC 9.2 started to ship arg docs in the form of the IntMap, which this PR also migrated to. Current changes to functions are seen as an improvement already & further PRs would work on argument documentation provisioning further.

[Anton-Latukha]

Overall, I'd liked to keep explicit return types of getDocumentation{,s}TryGhc of IO (Either GHC.ErrorMessages (Name, Either GetDocsFailure (Maybe HsDocString, Maybe (IntMap HsDocString)))) - it puts those complex return procedure explicitly. Before this, the errors were thrown into a monad & was required to be/was caught immediately up the stack, & during GHC API change of ErrorMessages - I do not know how I'd figured-out it. For now it became Either & allowed me to do safety guaranteed changes working with the code.

Having exceptions explicitly in the types also allowed to figure out how to do rebasing onto GHC 9.2 changes & the API changes of GHC.

Having Map Name (Maybe HsDocString, Maybe (IntMap HsDocString) also would be helpful for further work on arg docs. Before this code pretended to have argdocs always, stubbing the Nothing case, which not helped with thinking how to parse & provision them. First I need to know precisely what IntMap holds in which cases & precisely when Nothing is returned. Having explicit types helps to guide and align the code.

After current changes are figured-out, code may return to trow/catching the exceptions, but I'd highly preferred to have Map Name (Maybe HsDocString, Maybe (IntMap HsDocString) or maybe HashMap Name (Maybe HsDocString, Maybe (IntMap HsDocString).