Document all bazel rules provided in the repository#13
Document all bazel rules provided in the repository#13Szelethus merged 13 commits intoEricsson:mainfrom
Conversation
I extended the README file to give a bit more detail on what each of the rules do and how can one load and use them. In particular, I wanted to draw attention to the difference in between codechecker_test and code_checker_test. Considering that many of these things are subject to change, I didn't wanna go overboard detailing each parameter.
nettle
left a comment
nettle
left a comment
There was a problem hiding this comment.
Looks good as a start! Please see some comments.
|
I updated the summary to lay out the aim of the PR, and have created issues about the problems we raised here. As the codebase matures and these problems are fixed, rules are merged, I'm more than happy to ammend. Do you think this page is okay now? |
nettle
left a comment
nettle
left a comment
There was a problem hiding this comment.
General recommendation/comment: I think we should keep this simpler and do not describe things which are not working, not implemented, may cause questions we have no answers to etc. We will add details later. Besides (and this is important!) - nobody reads the documentation when everything is intuitive and working. And everyone is always angry at misleading documentation. Another thing - the best documentation is working example. Besides, README must be a very short document and not an academic paper. We should consider wiki with API description instead.
dkrupp
left a comment
dkrupp
left a comment
There was a problem hiding this comment.
I think it is good approach that we document the purpose of each rule in a consize way, because any potential user and/or contributor of this project would better understand the intended purpose of the rules and implementation status, which is important in an evolving project like this.
Adding API documentation (to the bazel rules) is a good idea.
I think with the minor corrections, the documentation is ready to land.
nettle
left a comment
nettle
left a comment
There was a problem hiding this comment.
There is one broken link and a few suggestions
|
I made some changes today but the patch is still not ready for another round of reviews. |
|
Mind that it seems like simply writing |
|
I think the patch is ready for another round. @nettle, @dkrupp, I've tried to address all your inline comments, either by fixing them or providing satisfactory answers. Where I felt it was appropriate, I marked the conversation resolved, but where I had some lingering doubt, I left that decision for you. What do you think needs to be done before merging this? @furtib Is the thread regarding the output directory correct according to the best of your knowledge? Summarizing the PR summary, I don't see this PR as the final stage in terms documentation, just a step in what I believe to be the right direction. |
Szelethus
dismissed
nettle’s stale review
We discussed in a meeting that @nettle has no time to review the PR further, and is not opposed to us merging it if we feel it's ready.
I extended the README file to give a describe each rule currently found in the repository do and how can one load and use them. In particular, I wanted to draw attention to the difference in between codechecker_test and code_checker_test. Considering that many of these things are subject to change, I didn't wanna go overboard detailing each parameter yet. This I hope is one PR among many aiming to improve our documentation. Considering that we are still in the early stages of this repository, the aim and scope are modest, and I'm not trying terribly hard to target a specific audience (soon-to-be-users, contributors, etc). Its simply an informal first impression page where every currently user-facing rules are described at least minimally. There many other things that need to be done: * Specify the minimal requirements and environment needed to pass all tests as they are now (Ericsson#29, Ericsson#35 ) * A simple copy-paste command line to set up the repository and its requirements via apt, not only modules * Have an actual user documentation, and update CONTRIBUTING.md. Preview is here: https://github.com/Szelethus/codechecker_bazel/blob/readme_update/README.md
4 participants
I extended the README file to give a describe each rule currently found in the repository do and how can one load and use them. In particular, I wanted to draw attention to the difference in between codechecker_test and code_checker_test. Considering that many of these things are subject to change, I didn't wanna go overboard detailing each parameter yet.
This I hope is one PR among many aiming to improve our documentation. Considering that we are still in the early stages of this repository, the aim and scope are modest, and I'm not trying terribly hard to target a specific audience (soon-to-be-users, contributors, etc). Its simply an informal first impression page where every currently user-facing rules are described at least minimally.
There many other things that need to be done:
Preview is here: https://github.com/Szelethus/codechecker_bazel/blob/readme_update/README.md