Hi Arpit,
thank you for paying attention to our first suggestions. Having read your proposal shows that you are on the right track, and it's great that you have shown examples and code snippets of what the project entitles. I believe this is a good first draft!
There are just a couple of remarks that I'd like to bring up for further discussion rather than correction suggestions of some sort:
A) Right in your introduction, you mention "it would be great to create a tool which not only allows to create YAML files (...) but also give an abstract representation of the header". Keep in mind these two functionalities are not necessarily intended to be contained in a single tool, and that these can be two completely different and independent tools, that might run stand-alone, and that might be later integrated into gr_modtool (which already includes some API for creating YAML, but you already noticed that). The modularity would help keep things clean and tidy and would invite for scalability.
B) When you list the primary features of the project, the first item is "Implementation of both the parsing tools (libclang with python and pygccxml)". In that point, it isn't clear for me if you are referring to two different tools, i.e. YAML generator and abstract representation generator (which would play along well with my first remark), or if you are referring to a single tool that is written once libclang with python and then written in pygccxml. It might be worth being more specific in this point just to not leave room for doubts. Also, it isn't required that the project is written all the way using both libclang and pygccxml (or any other for the matter). One of them might be chosen based on a preliminary selection process and then used for the project (see next point D).
C) (summarizing): you repeatedly refer to the project as "this tool" (singular) and "both parsers" (plural), "both tools" (contradictory to the _this tool_) but the specification of what exactly is the outcome is unclear. Going straight to the idea outline [1], the proposed idea is:
- One that turns a block definition into an abstract representation,
- One that takes the abstract representation and produces a YAML file for GRC
- API support for the outcome
- Make gr_modtool use that API
Clearly, your proposal is free to bend the outcome of the idea if it's for the best. However, my point is that the idioms that you are using make it unclear of what the project will be about right from the introduction, and it's required to read on to get the idea. I suggest that you modify your first sections to make them more concise of what is to be expected from your work.
D) In the "implementation of the parsing tools" sections, you have examples of the general parsing using the said pygccxml and libclang. The examples are fine, but have you found maybe some advantages of one over the other, in terms of usage, the complexity of the outcome, etc? Does one of these two options seem more promising to be used throughout the project over the other? Or is there a real advantage of providing support for both? Clearly, _convenience_ might also be a use case (i.e. A user is more familiar with one of the parsers, so he chooses _that_ one). However, I wonder about the cost/benefit of that matter. Would you say that supporting both parsers is worth it?
E) In the section "Create YAML files for GRC" you mention that this is "the most important part of the project", and this is arguable. You see, YAML files are already being generated to some extent for GRC based on the written code. But what is expected from the generated tools, in general, is to be able to extract as much information as possible in a portable format. See [2]. It's important to keep this in mind as it might affect the view that you have of the project.
More points might come along as we work together on the proposal. Others probably might want to chime in into the discussion, so we might expect the document to be tweaked a couple of times before the final draft. But you've done some really good work so far! Keep it up!
Cheers,
-Nico