func не является функцией User. Это особенность муфты User-Library<T>.

Помещать его в User, если он не имеет четкой семантики за пределами использования Library<T>, — плохая идея. Если у него есть четкая семантика, он должен сказать, что он делает, и его удаление должно быть явно плохой идеей.

Размещение его в Library<T> не работает, потому что его поведение является функцией T в Library<T>.

Ответ заключается в том, чтобы не размещать его ни в одном месте.

template<class T> struct tag_t{ using type=T; constexpr tag_t(){} };
template<class T> constexpr tag_t<T> tag{};

Сейчас в Library.h:

struct ForLibrary;
template<class T> class Library{
  public: T* node=nullptr;
  public: void utility(){
    func( tag<ForLibrary>, node ); // #1
  }
};

in User.h:

struct ForLibrary;
class User{ 
/** This function is for "Library" callback */
public:
  friend void func( tag_t<ForLibrary>, User* self ) {
    // code
  }
};

или просто поместите это в то же пространство имен, что и User, или в то же пространство имен, что и ForLibrary:

friend func( tag_t<ForLibrary>, User* self );

Прежде чем удалить func, вы отследите ForLibrary.

Он больше не является частью «общедоступного интерфейса» User, поэтому не загромождает его. Это либо друг (помощник), либо свободная функция в том же пространстве имен, что и User, или Library.

Вы можете реализовать его там, где вам нужен Library<User>, а не в User.h или Library.h, особенно если он просто использует общедоступные интерфейсы User.

Здесь используются такие методы, как «диспетчеризация тегов», «поиск в зависимости от аргумента», «функции друзей» и предпочтение бесплатных функций методам.

Со стороны пользователя я бы использовал crtp для создания интерфейса обратного вызова и заставил пользователей использовать Это. Например:

template <typename T>
struct ICallbacks
{
    void foo() 
    {
        static_cast<T*>(this)->foo();
    }
};

Пользователи должны наследовать этот интерфейс и реализовать обратный вызов foo().

struct User : public ICallbacks<User>
{
    void foo() {std::cout << "User call back" << std::endl;}
};

Самое приятное в этом то, что если Library использует интерфейс ICallback и User забывает реализовать foo(), вы получите хорошее сообщение об ошибке компилятора.

Обратите внимание, что здесь нет виртуальной функции, поэтому здесь нет снижения производительности.

Со стороны библиотеки я бы вызывал эти обратные вызовы только через ее интерфейсы (в данном случае ICallback). Следуя OP при использовании указателей, я бы сделал что-то вроде этого:

template <typename T>
struct Library
{
    ICallbacks<T> *node = 0;

    void utility()
    {
       assert(node != nullptr);
       node->foo();
    }
};

Обратите внимание, что таким образом все автоматически документируется. Совершенно очевидно, что вы используете интерфейс обратного вызова, и node — это объект, у которого есть эти функции.

Ниже приведен полный рабочий пример:

#include <iostream>
#include <cassert>

template <typename T>
struct ICallbacks
{
    void foo() 
   {
       static_cast<T*>(this)->foo();
   }
};

struct User : public ICallbacks<User>
{
     void foo() {std::cout << "User call back" << std::endl;}
};

template <typename T>
struct Library
{
    ICallbacks<T> *node = 0;

    void utility()
    {
        assert(node != nullptr);
        node->foo();
    }
};

int main()
{
    User user;

    Library<User> l;
    l.node = &user;
    l.utility();
}

Test.h

#ifndef TEST_H
#define TEST_H

// User Class Prototype Declarations
class User;

// Templated Wrapper Class To Contain Callback Functions
// User Will Inherit From This Using Their Own Class As This
// Class's Template Parameter
template <class T>
class Wrapper {
public:
    // Function Template For Callback Methods. 
    template<class U>
    auto Callback(...) {};
};

// Templated Library Class Defaulted To User With The Utility Function
// That Provides The Invoking Of The Call Back Method
template<class T = User>
class Library {
public:
    T* node = nullptr;
    void utility() {
        T::Callback(node);
    }
};

// User Class Inherited From Wrapper Class Using Itself As Wrapper's Template Parameter.
// Call Back Method In User Is A Static Method And Takes A class Wrapper* Declaration As 
// Its Parameter
class User : public Wrapper<User> {
public:
    static void Callback( class Wrapper* ) { std::cout << "Callback was called.\n";  }
};

#endif // TEST_H

main.cpp

#include "Test.h"

int main() {

    Library<User> l;
    l.utility();

    return 0;
}

Вывод

Callback was called.

Я смог скомпилировать, собрать и запустить это без ошибок в VS2017 CE в Windows 7 — 64-битный Intel Core 2 Quad Extreme.

Какие-нибудь мысли?

Я бы рекомендовал соответствующим образом назвать класс-оболочку, а затем для каждой конкретной функции обратного вызова, имеющей уникальную цель, назвать их соответствующим образом в классе-оболочке.

Изменить

Поигравшись с этой магией шаблона, нет такой вещи... Я закомментировал шаблон функции в классе Wrapper и обнаружил, что он не нужен. Затем я закомментировал class Wrapper*, который является списком аргументов для Callback() в User. Это дало мне ошибку компилятора, в которой говорилось, что User::Callback() не принимает 0 аргументов. Поэтому я оглянулся на Wrapper, так как User наследуется от него. На данный момент Wrapper — это пустой шаблон класса.

Это заставило меня взглянуть на Library. Библиотека имеет указатель на User в качестве общедоступного члена и функцию utility(), которая вызывает метод User's static Callback. Именно здесь вызывающий метод принимает указатель на объект User в качестве параметра. Так что это заставило меня попробовать это:

class User; // Prototype
class A{}; // Empty Class

template<class T = User>
class Library {
public: 
    T* node = nullptr;
    void utility() {
        T::Callback(node);
    }
};

class User : public A {
public:
    static void Callback( A* ) { std::cout << "Callback was called.\n"; }
};

И это правильно компилируется и строится как упрощенная версия. Однако; когда я думал об этом; версия шаблона лучше, потому что она выводится во время компиляции, а не во время выполнения. Итак, когда мы вернемся к использованию шаблонов, javaLover спросил меня, что означает class Wrapper* или находится в списке аргументов для метода Callback в классе User.

Я постараюсь объяснить это как можно яснее, но сначала класс-оболочка — это просто пустая оболочка шаблона, от которой наследуется User, и он ничего не делает, кроме как действует как базовый класс, и теперь он выглядит так:

template<class T>
class Wrapper {   // Could Be Changed To A More Suitable Name Such As Shell or BaseShell
};

Когда мы смотрим на класс User:

class User : public Wrapper<User> {
public:
    static void Callback( class Wrapper* ) { // print statement }
};

Мы видим, что User — это нешаблонный класс, который наследуется от шаблонного класса, но использует себя в качестве аргумента шаблона. Он содержит общедоступный статический метод, и этот метод ничего не возвращает, но принимает один параметр; это также очевидно в классе Library, параметр шаблона которого является классом User. Когда метод Library's utility() вызывает метод User's Callback(), параметр, ожидаемый библиотекой, является указателем на объект User. Поэтому, когда мы возвращаемся к классу User, вместо того чтобы объявлять его как указатель User* непосредственно в его объявлении, я использую пустой шаблон класса, от которого он наследуется. Однако, если вы попытаетесь сделать это:

class User : public Wrapper<User> {
public:
    static void Callback( Wrapper* ) { // print statement }
};

Вы должны получить сообщение о том, что Wrapper* отсутствует список аргументов. Мы могли бы просто сделать Wrapper<User>* здесь, но это избыточно, поскольку мы уже видим, что User наследуется от Wrapper, который берет сам себя. Таким образом, мы можем исправить это и сделать его чище, просто добавив префикс Wrapper* с ключевым словом class, поскольку это шаблон класса. Отсюда и магия шаблонов... ну, здесь нет никакой магии... только встроенная компилятором и оптимизация.

Хотя я знаю, что не отвечаю на ваш конкретный вопрос (как задокументировать функцию, которую нельзя удалить), я бы решил вашу проблему (сохранив, казалось бы, неиспользуемую функцию обратного вызова в базе кода), создав экземпляр Library<User> и вызвав utility() в модульном тесте (или, может быть, его лучше назвать тестом API...). Это решение, вероятно, будет масштабироваться и для вашего реального примера, если вам не нужно проверять каждую возможную комбинацию библиотечных классов и функций обратного вызова.

Если вам посчастливилось работать в организации, где требуются успешные модульные тесты и проверка кода, прежде чем изменения будут внесены в базу кода, это потребует изменения модульных тестов, прежде чем кто-либо сможет удалить функцию User::func(), и такое изменение, вероятно, поймает внимание рецензента.

Опять же, вы знаете свою среду, а я нет, и я понимаю, что это решение подходит не для всех ситуаций.

Вот решение с использованием класса Traits:

// Library.h:
template<class T> struct LibraryTraits; // must be implemented for every User-class

template<class T> class Library {
public:
    T* node=nullptr;
    void utility() {
        LibraryTraits<T>::func(node);
    }
};

// User.h:
class User { };

// must only be implemented if User is to be used by Library (and can be implemented somewhere else)
template<> struct LibraryTraits<User> {
    static void func(User* node) { std::cout << "LibraryTraits<User>::func(" << node << ")\n"; }
};

// main.cpp:

int main() {
    Library<User> li; li.utility();
}

Преимущества:

• По названию очевидно, что LibraryTraits<User> требуется только для взаимодействия User с Library (и может быть удалено после удаления либо Library, либо User.
• LibraryTraits может быть специализировано независимо от Library и User

Недостатки:

• Нет легкого доступа к закрытым членам User (сделка LibraryTraits другом User лишила бы его независимости).
• Если один и тот же func необходим для разных Library классов, необходимо реализовать несколько Trait классов (может быть решена реализациями по умолчанию, наследующими от других Trait классов).

Это сильно напоминает старый добрый дизайн, основанный на политике, за исключением того, что в вашем случае вы не наследовать класс Library от класса User. Хорошие имена — лучшие друзья любого API. Объедините это и известную фразу проектирования на основе политик (известность очень важна, потому что имена классов со словом Policy в нем сразу вызовут интерес у многих читателей кода), и, я полагаю, вы получите хорошо самодокументирующийся код.

• Наследование не приведет к снижению производительности, но даст вам возможность иметь Callback в качестве защищенного метода, что даст некоторый намек на то, что он должен быть унаследован и где-то использоваться.

• Иметь четко выделяющиеся и согласованные имена среди нескольких User-подобных классов (например, SomePolicyOfSomething в порядке вышеупомянутого проектирования на основе политик), а также аргументы шаблона для Library (например, SomePolicy, или я бы назвал его TSomePolicy).

• Наличие using объявления Callback в классе Library может привести к более четким и более ранним ошибкам (например, из IDE или современного clang, анализаторов синтаксиса visial studio для IDE).

Другим спорным вариантом может быть static_assert, если у вас C++>=11. Но в этом случае его нужно использовать в каждом User-подобном классе ((.

Не прямой ответ на ваш вопрос о том, как это документировать, но что-то, что следует учитывать:

Если ваш шаблон библиотеки требует реализации someFunction() для каждого используемого в нем класса, я бы рекомендовал добавить его в качестве аргумента шаблона.

#include <functional>
template<class Type, std::function<void(Type*)> callback>
class Library {
    // Some Stuff...
    Type* node = nullptr;
public:
    void utility() {
         callback(this->node);
    }
};

Можно сделать это еще более явным, чтобы другие разработчики знали, что это необходимо.

абстрактный класс — лучший способ заставить функцию не удаляться. Поэтому я рекомендую реализовать базовый класс с чистой виртуальной функцией, чтобы производный должен был определить функцию. ИЛИ вторым решением было бы иметь указатели на функции, чтобы производительность сохранялась за счет избежания дополнительных накладных расходов на создание и вызов V-таблицы.

Если не очевидно, что func() требуется в User, то я бы сказал, что вы нарушаете единую ответственность принцип. Вместо этого создайте класс адаптера адаптера, членом которого будет User.

class UserCallback {
  public:
    void func();

  private:
    User m_user;
}

Таким образом, существование UserCallback подтверждает, что func() является внешним обратным вызовом, и отделяет потребность Library в обратном вызове от фактических обязанностей User.