lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From NightOwl888 <...@git.apache.org>
Subject [GitHub] lucenenet issue #206: API Doc site generator using DocFx script
Date Wed, 30 May 2018 06:13:14 GMT
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?
    
    



---

Mime
View raw message