Keep comments associated with requirements of a concept

[milasudril]

I found an issue with Doxygen doxygen/doxygen#9569. You cannot add documentation on concept requirements. Then I tried to do something with python-clang (version 15), and indeed it gave no comments.

/**
 * \brief Defines the requirements of a "source"
 *
 * A source is something that can be read from, for example, an input buffer or a file.
 *
 * \ingroup de-serialization
 *
 */
template<class T>
concept source = requires(T a)
{
	/**
	 * \brief Shall try to consume next byte and return it. If it possible to consume another
	 *  byte, it shall return std::nullopt, which implies an End-Of-File condition.
	 */
	{ read_byte(a) } -> std::same_as<std::optional<char>>;
};

Becomes

CursorKind.TRANSLATION_UNIT, testdata/test.hpp, None
    CursorKind.CONCEPT_DECL, source, /**
 * \brief Defines the requirements of a "source"
 *
 * A source is something that can be read from, for example, an input buffer or a file.
 *
 * \ingroup de-serialization
 *
 */
        CursorKind.TEMPLATE_TYPE_PARAMETER, T, None
        CursorKind.REQUIRES_EXPR, , None
            CursorKind.PARM_DECL, a, None
                CursorKind.TYPE_REF, T, None
            CursorKind.DECL_REF_EXPR, , None
                CursorKind.OVERLOADED_DECL_REF, read_byte, None
            CursorKind.DECL_REF_EXPR, a, None
            CursorKind.NAMESPACE_REF, std, None
            CursorKind.TEMPLATE_REF, same_as, None
            CursorKind.NAMESPACE_REF, std, None
            CursorKind.TEMPLATE_REF, optional, None

From this

/**
 * Given a cursor that represents a declaration, return the associated
 * comment's source range.  The range may include multiple consecutive comments
 * with whitespace in between.
 */
CINDEX_LINKAGE clang_Cursor_getCommentRange[CXCursor C);

Maybe that is not possible, since the requirements is not treated as declarations. Would it be possible to make individual requirements behave more like class members?

[llvmbot]

@llvm/issue-subscribers-clang-frontend

Author: Torbjörn Rathsman (milasudril)

I found an issue with Doxygen https://github.com/doxygen/doxygen/issues/9569. You cannot add documentation on concept requirements. Then I tried to do something with python-clang (version 15), and indeed it gave no comments.

/**
 * \brief Defines the requirements of a "source"
 *
 * A source is something that can be read from, for example, an input buffer or a file.
 *
 * \ingroup de-serialization
 *
 */
template<class T>
concept source = requires(T a)
{
	/**
	 * \brief Shall try to consume next byte and return it. If it possible to consume another
	 *  byte, it shall return std::nullopt, which implies an End-Of-File condition.
	 */
	{ read_byte(a) } -> std::same_as<std::optional<char>>;
};

Becomes

CursorKind.TRANSLATION_UNIT, testdata/test.hpp, None
    CursorKind.CONCEPT_DECL, source, /**
 * \brief Defines the requirements of a "source"
 *
 * A source is something that can be read from, for example, an input buffer or a file.
 *
 * \ingroup de-serialization
 *
 */
        CursorKind.TEMPLATE_TYPE_PARAMETER, T, None
        CursorKind.REQUIRES_EXPR, , None
            CursorKind.PARM_DECL, a, None
                CursorKind.TYPE_REF, T, None
            CursorKind.DECL_REF_EXPR, , None
                CursorKind.OVERLOADED_DECL_REF, read_byte, None
            CursorKind.DECL_REF_EXPR, a, None
            CursorKind.NAMESPACE_REF, std, None
            CursorKind.TEMPLATE_REF, same_as, None
            CursorKind.NAMESPACE_REF, std, None
            CursorKind.TEMPLATE_REF, optional, None

From this

/**
 * Given a cursor that represents a declaration, return the associated
 * comment's source range.  The range may include multiple consecutive comments
 * with whitespace in between.
 */
CINDEX_LINKAGE clang_Cursor_getCommentRange[CXCursor C);

Maybe that is not possible, since the requirements is not treated as declarations. Would it be possible to make individual requirements behave more like class members?

[llvmbot]

@llvm/issue-subscribers-c-20

Author: Torbjörn Rathsman (milasudril)

I found an issue with Doxygen https://github.com/doxygen/doxygen/issues/9569. You cannot add documentation on concept requirements. Then I tried to do something with python-clang (version 15), and indeed it gave no comments.

/**
 * \brief Defines the requirements of a "source"
 *
 * A source is something that can be read from, for example, an input buffer or a file.
 *
 * \ingroup de-serialization
 *
 */
template<class T>
concept source = requires(T a)
{
	/**
	 * \brief Shall try to consume next byte and return it. If it possible to consume another
	 *  byte, it shall return std::nullopt, which implies an End-Of-File condition.
	 */
	{ read_byte(a) } -> std::same_as<std::optional<char>>;
};

Becomes

CursorKind.TRANSLATION_UNIT, testdata/test.hpp, None
    CursorKind.CONCEPT_DECL, source, /**
 * \brief Defines the requirements of a "source"
 *
 * A source is something that can be read from, for example, an input buffer or a file.
 *
 * \ingroup de-serialization
 *
 */
        CursorKind.TEMPLATE_TYPE_PARAMETER, T, None
        CursorKind.REQUIRES_EXPR, , None
            CursorKind.PARM_DECL, a, None
                CursorKind.TYPE_REF, T, None
            CursorKind.DECL_REF_EXPR, , None
                CursorKind.OVERLOADED_DECL_REF, read_byte, None
            CursorKind.DECL_REF_EXPR, a, None
            CursorKind.NAMESPACE_REF, std, None
            CursorKind.TEMPLATE_REF, same_as, None
            CursorKind.NAMESPACE_REF, std, None
            CursorKind.TEMPLATE_REF, optional, None

From this

/**
 * Given a cursor that represents a declaration, return the associated
 * comment's source range.  The range may include multiple consecutive comments
 * with whitespace in between.
 */
CINDEX_LINKAGE clang_Cursor_getCommentRange[CXCursor C);

Maybe that is not possible, since the requirements is not treated as declarations. Would it be possible to make individual requirements behave more like class members?