def get_comment_syntax_map(comment_text):
    """Return dict mapping portions to respective categories.

    That is, we map each portion of the text to the name
    of the category that portion represents in the syntax.

    Comments only have two categories, which are normal
    text ('normal') and todo words ('todo_words').

    How we map the text is based on the behaviour observed
    in the vim editor, which highlights todo words within
    comments. Such todo words are the words TODO, XXX and
    FIXME.

    The dict itself contains indices of lines from the text
    mapped to another dict which contains the intervals in
    that line mapped to the category of text each interval
    contain.

    The intervals are 2-tuples of integers representing
    the [a, b) interval. Another way of seeing such
    integers is as the indices you'd use to grab the
    slice of text from the line representing the interval:
    line_text[a:b].

    For instance, if a line has the (0, 4) interval mapped
    to 'normal', it means the line text has normal text
    from the index 0 until the index 3. If you were to
    execute line_text[0, 4] you'd get a normal portion
    of text.


    Doctest
    =======

    An example in the form of a doctest can be seen below:

    >>> text = "### TODO hello world"
    >>> expected_output = {
    ...   0: {
    ...        (0, 4)  : 'normal',
    ...        (4, 8)  : 'todo_word',
    ...        (8, 20) : 'normal',
    ...      }
    ... }
    >>> get_comment_syntax_map(text) == expected_output
    True

    In other words, the output means that the text we
    provided, in its first line (index 0), has normal
    text from the index 0 until the 3 and then has
    text representing a todo word from the index 4
    until the index 7, then normal text again from
    index 8 until the index 19.


    No Syntax Errors
    ================

    This function wasn't set to raise SyntaxMappingError
    as was the case for the equivalent function which maps
    syntax for Python source code, for instance.

    This is so because comments don't have wrong syntax.
    They either have special syntax ("todo" words) or no
    syntax at all, but we don't expect any syntax-related
    errors to be raised while mapping syntax for comments.
    """
    ### return dict

    return {
        ### each item in such dict is composed by the index of
        ### a line to which a dict is mapped
        line_index: {
            ## this other dict associates intervals of the line
            ## to the name of the syntax category the text in
            ## that interval represents
            interval: syntax_category_name
            ## we get the intervals and respective categories
            ## from passing the line text through a special
            ## function
            for interval, syntax_category_name in get_line_syntax_intervals(line_text)
        }
        ### we grab pairs of line index/ line text from lines
        ### which are not empty
        for line_index, line_text in enumerate(comment_text.splitlines())
        if line_text
    }
Return dict mapping portions to respective categories.

    That is, we map each portion of the text to the name
    of the category that portion represents in the syntax.

    Comments only have two categories, which are normal
    text ('normal') and todo words ('todo_words').

    How we map the text is based on the behaviour observed
    in the vim editor, which highlights todo words within
    comments. Such todo words are the words TODO, XXX and
    FIXME.

    The dict itself contains indices of lines from the text
    mapped to another dict which contains the intervals in
    that line mapped to the category of text each interval
    contain.

    The intervals are 2-tuples of integers representing
    the [a, b) interval. Another way of seeing such
    integers is as the indices you'd use to grab the
    slice of text from the line representing the interval:
    line_text[a:b].

    For instance, if a line has the (0, 4) interval mapped
    to 'normal', it means the line text has normal text
    from the index 0 until the index 3. If you were to
    execute line_text[0, 4] you'd get a normal portion
    of text.


    Doctest
    =======

    An example in the form of a doctest can be seen below:

    >>> text = "### TODO hello world"
    >>> expected_output = {
    ...   0: {
    ...        (0, 4)  : 'normal',
    ...        (4, 8)  : 'todo_word',
    ...        (8, 20) : 'normal',
    ...      }
    ... }
    >>> get_comment_syntax_map(text) == expected_output
    True

    In other words, the output means that the text we
    provided, in its first line (index 0), has normal
    text from the index 0 until the 3 and then has
    text representing a todo word from the index 4
    until the index 7, then normal text again from
    index 8 until the index 19.


    No Syntax Errors
    ================

    This function wasn't set to raise SyntaxMappingError
    as was the case for the equivalent function which maps
    syntax for Python source code, for instance.

    This is so because comments don't have wrong syntax.
    They either have special syntax ("todo" words) or no
    syntax at all, but we don't expect any syntax-related
    errors to be raised while mapping syntax for comments.
    
nodezator/syntaxman/syntaxes/comment.py