Page MenuHomePhabricator

[lldb][docs] Document SBType
ClosedPublic

Authored by teemperor on Jun 1 2021, 5:17 AM.

Details

Reviewers
mib
Group Reviewers
Restricted Project
Commits
rG11e2922bb7ad: [lldb][docs] Document SBType
Summary

This documents the behaviour of the different SBType functions with notes for the
language-specific behaviour for C/C++/Objective-C. All of this reflects the current
behaviour of LLDB (even though that also means some functions behave kinda weird
but at least they are now documented to be weird)

Diff Detail

Event Timeline

teemperor created this revision.Jun 1 2021, 5:17 AM
teemperor requested review of this revision.Jun 1 2021, 5:17 AM

The language here might shift between functions and needs to be synced up (that patch was written over a few weeks during some build/test idle time). But the patch seems good enough for a draft.

mib accepted this revision.Jun 1 2021, 9:37 AM
mib added a subscriber: mib.

Left few comments regarding the phrasing but LGTM! Thanks for doing it!

lldb/bindings/interface/SBType.i
372

Could you keep the same style as the previous function docstring ?

411

Same

427

Same + newline

443

Same

458

Same

This revision is now accepted and ready to land.Jun 1 2021, 9:37 AM
shafik added a subscriber: shafik.Jun 1 2021, 10:41 AM
shafik added inline comments.
lldb/bindings/interface/SBType.i
338

Worth noting that anonymous structs are a GNU extension in C++.

werat added a subscriber: werat.Jun 2 2021, 4:06 AM

Is this code used for auto-generated docs? Could be have this documentation in C++ definitions (lldb/API/SBType.h) as well? I usually just read the C++ source code, but I can imagine having the same docs in two places might be not the best idea...

Is this code used for auto-generated docs? Could be have this documentation in C++ definitions (lldb/API/SBType.h) as well? I usually just read the C++ source code, but I can imagine having the same docs in two places might be not the best idea...

Jepp, documenting this stuff in the C++ headers seems like a good idea. My current idea is that when the Python docs are done that I'll just copy them to the C++ headers (and add/remove the C++<->Python specific parts)

And I agree, having them in two places isn't great, but apparently the technology is barely there to even document the current SWIG interfaces itself (enums and overloaded functions are just really broken with Python), so I don't think we can do some form of single source publishing here (at least without writing our own tools[1]). The good thing is that the SB API is stable so once this is done we should hopefully rarely have to update the different versions of the docs. In any case, I think this is more of a discussion for the mailing list.

[1] Given how much pain it is to work with SWIG, I think the idea of "let's just make our own SWIG" is actually really popular around here. Maybe one day we'll reach the point where someone has enough, takes a week off and returns with the SWIG clone we all deserve :)

teemperor updated this revision to Diff 351819.Jun 14 2021, 4:02 AM
  • Make language more uniform
  • Point out anonymous struct is a GNU extension.
This revision was landed with ongoing or failed builds.Jun 14 2021, 4:19 AM
This revision was automatically updated to reflect the committed changes.