Python: Add a bunch of documentation. #3770
Conversation
|
Since this is documentation, perhaps @felicitymay would like to take a look? 🙂 |
I don't think there's any need to document the parts specific to metrics or defects, as I don't believe these are used anywhere.
If only we had been _somewhat consistent in how we named the parameters for these...
I didn't do the `toString` methods in this commit. I'm thinking they're better to do in a separate commit. (There are 48 undocumented instances!)
| /** | ||
| * Provides classes for working with external data. | ||
| */ |
There was a problem hiding this comment.
Having never heard about this before, I have no idea what this is actually about by just reading this comment. Looking through the source code, I can see this is used by the Thrift code. So I guess external data in this context means data that is part of the DB that is not Python code? (or would something like CSV and XML not be a part of this?)
Maybe we can expand this comment, or the one for ExternalData? 😊
There was a problem hiding this comment.
To be quite honest, I don't know exactly what these classes are used for. That's why I left some of the undocumented. (I can certainly make an educated guess about what they might represent, but I wouldn't feel comfortable making this the official documentation.)
As for the level of documentation, I can only refer you to the JavaScript equivalent: https://github.com/github/codeql/blob/master/javascript/ql/src/external/ExternalArtifact.qll
😉
Co-authored-by: Felicity Chapman <felicitymay@github.com> Co-authored-by: Rasmus Wriedt Larsen <rasmuswriedtlarsen@gmail.com>
Had this lying around for a while. Rebased it so hopefully none of the tests fail.