Clang/LLVM documentation.

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

Clang/LLVM documentation.

Manas 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

 


_______________________________________________
cfe-dev mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev