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 Mon, 12 Jun 2017 21:40:00 GMT
Github user NightOwl888 commented on the issue:

    https://github.com/apache/lucenenet/pull/206
  
    @Shazwazza 
    
    Thanks again. I took a look and documentation generated perfectly. The documentation and
code samples look great.
    
    I have done all of the grunt work to update the documentation comments to get rid of nearly
all of the compile warnings (at least in Visual Studio).
    
    However, there are a few issues/limitations that I found with the generated documentation,
as well as some features that would be nice to build in.
    
    ## Package Breakdown
    
    The Lucene documentation (https://lucene.apache.org/core/4_8_0/) breaks the API down by
package first, and then allows you to drill into types. 
    
    I am torn between that approach and putting everything into one "bucket" like we currently
have, which is similar to MSDN. The filter makes it easy to find something specific, but it
is difficult to tell where the core types are vs the specialized add-ons.
    
    The amount of data that you have to wade through is a bit overwhelming. For example, the
navigation initializes with mostly obscure analysis packages in view before more useful namespaces.
If we could somehow arrange it so the main namespaces show up at the top level, and allow
a drill down to the levels below (or at least have an additional navigation feature that does
this), that would seem more appropriate. 
    
    ## .NET Core vs .NET Framework
    
    The APIs for each framework are similar, but there are places where they diverge. Namely,
there are several types that are not supported in .NET Core and therefore don't exist. One
such example is [ConcurrentMergeScheduler](https://github.com/apache/lucenenet/blob/master/src/Lucene.Net/Index/ConcurrentMergeScheduler.cs).
If you look at that class in the documentation, there is no indication at all that it doesn't
exist in .NET Core.
    
    Ideally, the fix for that would be to generate framework/version specific documents with
a "drop down" (or similar) navigation feature that allows switching between available frameworks
(just like MSDN). Is this (or a workaround) possible?
    
    ## Missing Links
    
    Some of the documentation I updated have links that are not being generated in the output
even though they show up fine in Intellisense. Here are some problematic files:
    
    `/api/Lucene.Net.Codecs.Bloom.html`
    `/api/Lucene.Net.Codecs.Lucene46.Lucene46FieldInfosFormat.html`
    
    In the first case, several of the links (such as CodecHeader) are not showing up. In the
second case, all of them are showing up except for the one after Attributes. I haven't figured
out why this is the case.
    
    But actually this is a symptom of another problem. In Lucene, they are able to change
the link text to a code reference, but I haven't worked out what the syntax for that is (if
it is even possible). You can see [here](https://lucene.apache.org/core/4_8_0/core/org/apache/lucene/codecs/lucene46/Lucene46FieldInfosFormat.html)
that the link after Attributes has the text `Map<String, String>` but it links to the
documentation for `DataOutput.writeStringStringMap()`. 
    
    I tried the obvious way to create that type of link (`<see cref="SomeClass">link
text</see>`), but that just makes the whole thing disappear. If you have any insight
how this could be done I would appreciate it.
    
    ## HTML pages
    
    I mentioned this before, but after looking at this there are more than 250 HTML pages.
So this is a huge amount of missing documentation and most of the code samples are in it.
I recall reading that some documentation generators allow you to specify "namespace documentation",
and if that is the case with DocFx, perhaps we should use that to solve this.
    
    If you could provide a specification as to what format the "package documentation" needs
to be in (i.e. Markdown) and what convention it needs to follow (where the documentation needs
to be in order to show up under a specific namespace), I would be happy to put together a
tool to convert the existing HTML pages to that format and location.
    
    ## Viewport Width
    
    Minor complaint. On a large monitor, only about 2/3 of the available width is being utilized.
I checked and regular MSDN pages are using roughly 10% more width, and some of the newer pages
([example](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/list))
are using about 25% more of the available width. Is there a way to specify the maximum width
be wider?



---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message