[GitHub] lucenenet issue #206: API Doc site generator using DocFx script

[NightOwl888 <gi...@git.apache.org>]

Github user NightOwl888 commented on the issue:

    https://github.com/apache/lucenenet/pull/206
  
    > have fixed up a bunch of xref's
    
    To save a bunch of manual work, I created the https://github.com/apache/lucenenet/tree/master/src/dotnet/tools/JavaDocToMarkdownConverter tool. The idea is that we don't change the xrefs in the markdown docs manually, but keep refining the tool to generate them correctly. Once we get the tool to account for most/all of the special cases, we should then do a final automated conversion of the documentation before manually going through them and fixing up the rest of the links/code examples.
    
    > One problem however is the TestFramework because all of the classes in there are not in a TestFramework namespace and instead they overlap with other namespaces in different packages which confuses the docs. It will build with it in but when navigating the docs you might end up randomly under the TestFramework. To fix this we would probably need to change the namespace of the classes in the TestFramework project to be something like Lucene.Net.TestFramework.* ... I'm happy to do this if that's ok to do!
    
    In Java, the test framework was a component that could be added to projects in order to test applications made by Lucene. However, whoever began porting the test framework wasn't concerned with making the TestFramework into a component, and I didn't realize until late in the game that this was the case. Our test framework has some limitations that are preventing it from being made into a NuGet package for general use:
    
    1. The quality of the port is sub-par
    2. In the .NET ecosystem, there isn't a single unit test framework that is used by the majority as there is in Java, so the test framework would need to be refactored to able to plug in to NUnit, xUnit, MSTest, and possibly other test frameworks
    3. The documentation is incomplete
    4. There are some components that were not ported because they were not required for testing Lucene.Net, but they would need to be re-evaluated to see if they are useful to others
    
    As a result, making the TestFramework into a NuGet package that can be shipped would require quite a bit of effort.
    
    IMO, we should remove the TestFramework from the docs for now since those docs are neither complete nor useful to end users, but make it fairly easy to revert in case someone eventually makes the effort to make TestFramework into a shippable component.
    
    I see where you are going with the namespaces. However, it makes things smoother from a user perspective to be able to import a single namespace that covers both the component that is being utilized in the test and the actual test cases from the TestFramework (far fewer imports), plus that is the way it was done in Java. I am not going to argue that we must keep it this way, but being that there are several examples of namespaces that span multiple libraries in the .NET Framework itself (for example, mscorlib.dll), it seems like there should be something built into the documentation framework to make it possible to determine which assembly it is in without having to resort to naming every namespace after its assembly. Could you give it another pass to see if this is possible?
    
    



---