[Docs] Complaints about the LLVM/Clang web based documentation.

[Tanya Lattner via Docs]

Bill,

Thank you for the suggestions as we really appreciate the feedback. This list was actually used for Google Summer of Docs and not utilized by a larger crowd. It would be best to email llvm-dev. However, I’ll see if maybe this can be added to the website as a project in hopes someone will take it up.

Thanks,
Tanya 

> On Nov 5, 2020, at 1:25 PM, Crocker, William via Docs <docs at lists.llvm.org> wrote:
> 
> Hello:
>  
> I want to thank you for all of the great work on Clang/LLVM.
> But, I need to complain about the documentation.
>  
> I am getting the doc from here, for example.
>    https://clang.llvm.org/doxygen/classclang_1_1Expr.html <https://clang.llvm.org/doxygen/classclang_1_1Expr.html>
> If that is not the latest and greatest, please let me know.
>  
> 1 - Very few of the functions have a description of any kind.
>  
>     I know this is tough and a lot of work,
>     but how long has clang been around?
>  
> 2 - If the argument list to a function is too long,
>     and you are zoomed in too far (for readability) it drives the
>     right most columns off the right hand edge of the page.
>     For example:
>  
>     https://clang.llvm.org/doxygen/classclang_1_1BinaryOperator-members.html <https://clang.llvm.org/doxygen/classclang_1_1BinaryOperator-members.html>
>  
>     Recommendation: Set some upper limit and add new-lines after commas
>     in the argument list. Or use a table.
>  
> 3 - The return-type for functions is not part of the function list.
>  
>     For a beginner that is just as valuable as the name, argument list and description.
>     I assume Doxygen could be ordered to include the return type.
>  
> I compare your documentation with that for the Qt class library.
> Their doc is very good. Here is the Qt string class, for example:
>  
>     https://doc.qt.io/qt-5.9/qstring.html <https://doc.qt.io/qt-5.9/qstring.html>
>  
> Qt includes the return type, prominently.
> Qt wraps long argument lists. (I think they use a table so they get that for free.)
> Qt documents every function.
>  
> Yes, Qt is a commercial product, but it offers the (L)GPL and is contributed
> to greatly by the outside world.
>  
> Thanks.
>  
> Bill
>  
> _______________________________________________
> Docs mailing list
> Docs at lists.llvm.org <mailto:Docs at lists.llvm.org>
> https://lists.llvm.org/cgi-bin/mailman/listinfo/docs <https://lists.llvm.org/cgi-bin/mailman/listinfo/docs>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/docs/attachments/20201128/79ccfbca/attachment.html>