Annotations
===========

Annotate components with user-specific information for future use.

Annotations do not impact formatting.

Creating annotations
--------------------

Use mark tools to create annotations:

<abjad>
annotation = marktools.Annotation('special pitch', pitchtools.NamedChromaticPitch('bs'))
</abjad>

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

Attaching annotations
---------------------

Attach annotations by calling them:

<abjad>
note = Note("c'4")
annotation(note)
</abjad>

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

Creating and attaching annotations in one step
----------------------------------------------

Create and attach annotations in one step like this:

<abjad>
another_annotation = marktools.Annotation('special pitch', pitchtools.NamedChromaticPitch('bs'))(note)
</abjad>

<abjad>
another_annotation
print another_annotation <hide
</abjad>

Getting annotations
-------------------

Use mark tools to get annotations:

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

Detaching annotations by hand
-----------------------------

Detach annotations by hand:

<abjad>
annotation.detach_mark( )
</abjad>

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

Detaching annotations automatically
-----------------------------------

Or use mark tools to detach all annotations at once:

<abjad>
print marktools.detach_annotations_attached_to_component(note)
</abjad>

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

Inspecting attachment
---------------------

Use ``start_component`` to inspect attachment:

<abjad>
annotation(note)
</abjad>

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

Inspecting name
---------------

Use ``name`` to get the name of any annotation:

<abjad>
annotation.name
print repr(annotation.name) <hide
</abjad>

Inspecting value
----------------

And use ``value`` to get the value of any annotation:

<abjad>
annotation.value
print repr(annotation.value) <hide
</abjad>
