Geek asks and answers

Interface Documentation

I was wondering how I should document interface in your application IResource. Since I was coding the engine, not the library, I decided that the documentation should contain recommendations on how to write interface implementations; this is normal?

Also, could you please take a look at my interface and tell me if there are enough comments?

/**
    Interface that should be implemented by all resources. Implementing
    this interface is necessary for compatibility with the ResourceManager
    class template.

    \note Documentation of this interface includes guidelines on how
    implementations should be written.

    \see ResourceManager
                                                                              */
class IResource
{
  public:
    /**
        Loads resource data from a file. If data is already loaded,
        the function should return immediately.

        \throw std::exception Should throw on any failure to load the
        resource. If the resource is already loaded, don't throw, just
        return (as previously indicated).

        \note Access to this function should also be provided directly
        from a constructor. That constructor should catch any exceptions
        and throw them further to its caller.
                                                                              */
    virtual void loadFromFile(const std::string& file) = 0 ;
    /**
        All general guidelines from loadFromFile() also apply to this
        function. Additionally, the resource should not take possession of
        the buffer; the buffer should be safe to delete after loading.
                                                                              */
    virtual void loadFromMemory(const char* buffer, std::size_t size) = 0;
    /**
        Frees the data currently held by the resource object. Should
        return immeditelly if no data is loaded.
                                                                              */
    virtual void free() = 0;
    virtual bool isLoaded() const = 0;
};

Change: . A related discussion will open.

Following mostly the conversations in Johann Gerell's comment section of the answer , I opened a fairly long thread on programers.stackexchange. You can check it out here:
Types of Unified and Responsible Information

+3
source share
3

; .

, , , . "will": ; . : , . , .

. ? , ? - ?

, . - .

const char* - , const void*. , (, , ). ?

. .

, .

+3

, .

:

  • . , ( doxygen).
  • isLoaded?
  • doxygen. , , .
+3

, , ( ) . , IResource , resource-ish, , . , . IResource. , isLoaded, - . .

, :

class IResource
{
public:
    virtual SomeCommonResourceBehavior(...) = 0;

    virtual ~IResource() {}
};

class IResourceFactory
{
public:
    virtual std::unique_ptr<IResource> CreateFromFile(...) = 0;
    virtual std::unique_ptr<IResource> CreateFromMemory(...) = 0;

    virtual ~IResourceFactory() {}
};

Thus, when you see a reference or non-zero pointer to IResourceanywhere in your code, you know that it has already been created.

Also, if you cannot identify SomeCommonResourceBehaviorin IResource, then you probably thought a little wrong about your design.

EDIT: If you live on the land of pre-C ++ 0x, then this boost::unique_ptr<>is an alternative in the factory. If boost is not an alternative, std::auto_ptr<>better than the original pointer.

+1
source

More articles:


All Articles