Add a bit of documentation for typed COBOL AST#576
Add a bit of documentation for typed COBOL AST#576GBertholon wants to merge 1 commit intoOCamlPro:masterfrom
Conversation
nberth
left a comment
nberth
left a comment
There was a problem hiding this comment.
Interesting investigations. Some of my comments describe changes that could also be included in this PR. In addition, please fit the comments within 80 characters (on the lines that follow field definitions I think).
| field_redefinitions: item_redefinitions; | ||
| field_conditions: condition_names; (** Named conditions on the value of this field. *) | ||
| field_redefines: Cobol_ptree.qualname with_loc option; (** set iff this field is a redefinition. In that case this field must appear only inside item_redefinitions of the item it redefines. TODO: remove and extend item_redefintions type instead? *) | ||
| field_redefinitions: item_redefinitions; (** list alternative definitions for this field *) |
There was a problem hiding this comment.
I like the idea of extending item_redefinitions instead, probably with a record like { item_redefinitions_redefine: Cobol_ptree.qualname with_loc; item_redefinitions: item_definition wiith_loc nel; }, and then having field_redefinitions: item_redefinitions option; or something like that.
| artifacts: artifacts; | ||
| ptree: Cobol_ptree.compilation_group; (* Parse tree to access information missing in the typed AST. Is this field supposed to be stable? Should it only be used to access things that are inaccessible from cobol_unit ? *) | ||
| group: Cobol_unit.Types.group; (* The typed AST view as an unordered set of cobol_unit *) | ||
| artifacts: artifacts; (* Other typing artifacts *) |
There was a problem hiding this comment.
ptree is left here to ease its direct use by further passes in the analysis pipeline and queries in the LSP server (in which some position-based queries need to be performed on the parse-tree instead of the typed AST). Its presence here is not mandatory so it could be removed.
| { | ||
| data_items: Cobol_data.Types.data_definition named_n_ordered; | ||
| data_items: Cobol_data.Types.data_definition named_n_ordered; (* FIXME: Is the ordered part useful here ? Isn't it already exposed in a more structured way by data_records... *) | ||
| data_records: Cobol_data.Types.record list; |
There was a problem hiding this comment.
Here it makes sense to keep the ordered alternative as some data items are anonymous (fillers) and therefore do not belong to the resolution map. Additionally the data_definition brings more info than item_definitions themselves, that are the types accessible from the record descriptions.
| (* data items *) | ||
|
|
||
| (** data_definitions exposes two views on the records in DATA DIVISION: | ||
| - [data_items] contains all the fields with direct access by name. |
There was a problem hiding this comment.
Note it's not "fields" but "items": an item is either a field or a table, and a table is always anonymous.
So data_items "contains all data items with direct access by name or ordered access."
|
|
||
| (** data_definitions exposes two views on the records in DATA DIVISION: | ||
| - [data_items] contains all the fields with direct access by name. | ||
| - [data_records] is a list of record trees where each element represent a record root (typically at level 01) *) |
There was a problem hiding this comment.
| - [data_records] is a list of record trees where each element represent a record root (typically at level 01) *) | |
| - [data_records] is a list of record trees where each element represents a record definition (typically a level 01 or 77 data item) *) |
2 participants
This PR tries to add missing documentation on the typed COBOL AST.
Currently this is a draft with open questions where I need some input to produce a useful and missing documentation.
I also suggest some very minor refactorings that I am ready to perform.