FrankRay78
commented
1 month ago Broken links have been caused by https://github.com/spectreconsole/spectre.console/pull/1598, specifically links referencing examples (which have now been split out into its own project)
eg. https://github.com/spectreconsole/spectre.console/tree/main/examples/Cli/Injection (now a 404) should be: https://github.com/spectreconsole/examples/tree/main/examples/Cli/Injection
Proposed approach to fix
- Find and replace on the documentation markdown files
- Broken link checker on the published spectre.console website (?)
cc: @patriksvensson
Information
Describe the bug The documentation link on this page is broken in the official docs.
To Reproduce Open the relevant documentation, scroll to the "Dependency Injection" subheading, and click the first link.
Expected behavior I expected to find relevant documentation to help troubleshoot the
'TypeRegistrar' is inaccessible due to its protection levelerror when trying to copy/paste code from the dependency injection example.Screenshots This is the relevant error when following the example docs.
Additional context I haven't done a through search of the documentation for other examples, but there are likely more broken links in the docs.
Searching for the specific error I'm running into led me to this answer. I've found a few more answers in various issues, and all the relevant links are pointing to the old example links. I think I've found the relevant implementation of
TypeRegistrarat this location, but I'm not sure, since there are multiple classes with that name spread between the main project and the example docs.Recommendation to Rename Example Class After digging through various issues to try and find the correct links, it seems like I'm not the first person to struggle with implementing DI due to namespace collisions. I'd suggest updating the examples to not collide class names. Maybe rename the example to something like
MyExampleRegistrar? That would make it explicitly clear just from the class name that you're not supposed to find a default implementation.It's quite confusing to have the documentation implement a class with the exact same name as another private class. It makes it difficult to search for the right answers. It's easy to make the mistake of thinking you're failed to include the correct dependencies, rather than thinking you need to implement that same class in a different namespace. Renaming the example implementation would make things far more clear.
Recommendation to Improve Documentation for Better Clarity I know the documentation already says "TypeRegistrar is a custom class that must be created by the user", but it's easy to miss that single sentence when skimming dozens of pages of docs. I definitely made that mistake earlier today. That sentence is massively more important than the surrounding context. Updating the docs to move that section into a warning box would make it explicitly clear that you're not supposed to try and resolve access issues with the private TypeRegistrar. See the example mockup I made below.
Alternatively, since the example implementation is so basic, you could just provide a default registrar implementation for basic use cases, something like
SingletonTypeRegistrarin the library, and leave alternative implementations up to the end user. I'm only using DI for a basic global logger and a global settings cache, so I'm just going to end up copy/pasting the example Singleton class because I don't need anything more complex for my current project. Providing a default implementation would at least give people a simple option to get started, without increasing the maintenance burden by any real amount.Please upvote :+1: this issue if you are interested in it.