Easily add comments to objects

[tjlaboss]

Is your feature request related to a problem? Please describe.

I'm always frustrated when...

...creating objects from scratch and forgetting what they mean. There is not a natural way to do this at the moment, as comments, leading_comments, and trailing_comment can only get and not set.

>>> c = Cell("1 0  +2 -3  imp:n=1  $ existing comment")
>>> c.comments
[COMMENT: $ existing comment]
>>> x = montepy.input_parser.syntax_node.CommentNode("c New comment")
>>> c.comments.insert(0, x)
>>> c.comments
[COMMENT: $ existing comment]
>>> c.comments += [x]
  File "./montepy/mcnp_object.py", line 49, in wrapped
    add_line_number_to_exception(e, self)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "./montepy/exceptions.py", line 259, in add_line_number_to_exception
    raise error.with_traceback(trace)
  File "./montepy/mcnp_object.py", line 41, in wrapped
    return func(*args, **kwargs)
  File "./montepy/mcnp_object.py", line 150, in __setattr__
    descriptor.__set__(self, value)
    ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
AttributeError: property 'comments' of 'Cell' object has no setter

Error came from CELL: 1, mat: 0, DENS: None from an unknown file.

Describe the solution you'd like

Easily append, prepend, or extend an object's comments.

>>> c = Cell("1 0  +2 -3  imp:n=1")
>>> c.comments.append("Potato")
>>> c.comments.insert(0, "Mashed")
>>> c.comments.extend(["yeah"])
>>> c.comments
[COMMENT: "c Mashed",
 COMMENT: "c Potato",
 COMMENT: "c yeah"]

Describe alternatives you've considered

• Require the user to start a comment with a c or $ . If it starts with a c , it is a leading comment by default. If it starts with $ , it is an inline comment, of which only one should be allowed for now.
• Add getter and setter for inline_comment(s). Require the user to set one of: inline_comment(s), leading_comments, or trailing_comment. Keep comments as a pure getter.
• An additional category for comments native to objects: FCn and SCn.

[MicahGale]

I have thought about this on and off, and agree this is an issue.

The one thing though is: where in the syntax tree should these be added?

Instead of treating it as a list (the list that is returned is ephemeral), would something like: add_leading_comment and add_trailing_comment be good?

[tjlaboss]

Dealing with comments as a list would be ideal, granting the ability to append, pop, remove, and so on.

If it must be a function:
Trailing comments should be discouraged, as upon re-read MontePy will usually assume that they belong to the next object. A possible function signature could be:

def add_comment(self, text, trailing=False):

or potentially

def add_comment(self, text, location="leading"):
    if location not in {"leading", "inline", "trailing"}:
        raise ValueError

[MicahGale]

How do you intend for inline to be interpreted? The problem with a list is that these are plucked from the syntax tree and presented so when added to the list it is ambiguous where on the tree the comment should live.

[tjlaboss]

The first pass at inline implementation should just add a new inline comment to the first line of the input if available (Priority 3: Make it easy). A fancier implementation that allows them to be placed freely would be cool, but would have a poor utility to complexity ratio.

[MicahGale]

For something complex enough users can always do the sketchy thing of editing the obj._tree.