[cfe-dev] Clang/LLVM documentation.

[Crocker, William via cfe-dev]

I want to thank you for all of the great work on Clang/LLVM.

But, I need to complain about your documentation.

I am getting the doc from here, for example.
   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 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

    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

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20201106/997bec25/attachment-0001.html>