Comments
========

LilyPond comments begin with the ``%`` sign.
Abjad models LilyPond comments as marks.


Creating comments
-----------------

Use mark tools to create comments:

<abjad>
comment_1 = marktools.Comment('This is a comment before a note.', 'before')
</abjad>

<abjad>
comment_1
print repr(comment_1) <hide
</abjad>


Attaching comments to leaves
----------------------------

Attach comments to a note, rest or chord with ``attach_mark()``:

<abjad>
note = Note("cs''4")
show(note)
iotools.write_expr_to_ly(note, 'comments-1', 'oedo') <hide
</abjad>

<abjad>
comment_1.attach_mark(note)
</abjad>

<abjad>
f(note)
</abjad>

You can add comments before, after or to the right of any leaf.


Attaching comments to containers
--------------------------------

Use ``attach_mark()`` to attach comments to a container:

<abjad>
staff = Staff("c'8 d'8 e'8 f'8")
show(staff)
iotools.write_expr_to_ly(staff, 'comments-2', 'oedo') <hide
</abjad>

<abjad>
staff_comment_1 = marktools.Comment('Here is a comment before the staff.', 'before')
staff_comment_2 = marktools.Comment('Here is a comment in the staff opening.', 'opening')
staff_comment_3 = marktools.Comment('Here is another comment in the staff opening.', 'opening')
staff_comment_4 = marktools.Comment('Comment in the staff closing.', 'closing')
staff_comment_5 = marktools.Comment('Comment after the staff.', 'after')
</abjad>

<abjad>
staff_comment_1.attach_mark(staff)
staff_comment_2.attach_mark(staff)
staff_comment_3.attach_mark(staff)
staff_comment_4.attach_mark(staff)
staff_comment_5.attach_mark(staff)
</abjad>

<abjad>
f(staff)
</abjad>

You can add comments before, after, in the opening or in the closing of any container.


Getting the comments attached to a component
--------------------------------------------

Use mark tools to get all the comments attached to a component:

<abjad>
marktools.get_comments_attached_to_component(note)
print repr(marktools.get_comments_attached_to_component(note)) <hide
</abjad>

Abjad returns a tuple of zero or more comments.


Detaching comments from a component one at a time
-------------------------------------------------

Use ``detach_mark()`` to detach comments from a component one at a time:

<abjad>
comment_1 = marktools.get_comments_attached_to_component(note)[0]
</abjad>

<abjad>
comment_1.detach_mark()
print repr(comment_1.detach_mark()) <hide
</abjad>

<abjad>
f(note)
</abjad>


Detaching all comments attached to a component at once
------------------------------------------------------

Or use mark tools to detach all comments attached to a component at once:

<abjad>
for comment in marktools.get_comments_attached_to_component(staff): print comment
</abjad>

<abjad>
marktools.detach_comments_attached_to_component(staff)
</abjad>

<abjad>
f(staff)
</abjad>


Inspecting the component to which a comment is attached
-------------------------------------------------------

Use ``start_component`` to inspect the component to which a comment is attached:

<abjad>
comment_1.attach_mark(note)
</abjad>

<abjad>
comment_1.start_component
print repr(comment_1.start_component) <hide
</abjad>


Inspecting comments contents string
-----------------------------------

Use ``contents_string`` to inspect the written contents of a comment:

<abjad>
comment_1.contents_string
print repr(comment_1.contents_string) <hide
</abjad>
