How to write a better specification for a class?

[megatron 0]

Hey guys,

I don't see people do it so much on here, but I'm sure many of you have done it at least a few times and I know it can be done better than this.

This is my first time writing one, so cut me some slack. :)

/***********************************************************************
^                          Class Database<class T>                     ^
^                                                                      ^
^ Private Member Functions >                                           ^
^                                                                      ^
^                                                                      ^
^ std::vector<T> ObjectContainer :                                     ^
^                                                                      ^
^ Container for class T objects, all data elements are stored here     ^
^                                                                      ^
^                                                                      ^
^ std:::fstream FileHandler :                                          ^
^                                                                      ^
^ Stream object that handles opening files for the data retrieval      ^
^ and storing new databases                                            ^
^                                                                      ^
^                                                                      ^
^ std::string FileName :                                               ^
^                                                                      ^
^ Stores name of currently active file for easier file management      ^
^                                                                      ^
^ ==================================================================== ^
^                                                                      ^
^ Public Member Functions >                                            ^
^                                                                      ^
^                                                                      ^
^ Database() :                                                         ^
^                                                                      ^
^ Creates an uninitialised Database                                    ^
^                                                                      ^
^                                                                      ^
^ Database(std::string file) :                                         ^
^                                                                      ^
^ Takes filename as parameter and attempts to open the file            ^
^                                                                      ^
^                                                                      ^
^ bool OpenFile(std::string file) :                                    ^
^                                                                      ^
^ Returns true if file is able to be opened                            ^
^                                                                      ^
^                                                                      ^
^ bool ReadFile() :                                                    ^
^                                                                      ^
^ Returns true if current file was able to be read into the database   ^
^                                                                      ^
^                                                                      ^
^ void AddData(T& data) :                                              ^
^                                                                      ^
^ Adds a new piece of data to the end of the database                  ^
^                                                                      ^
^                                                                      ^
^ void EditData(T& data, unsigned int location) :                      ^
^                                                                      ^
^ The argument takes the new data to be stored at database location    ^
^                                                                      ^
^                                                                      ^
^ bool Save() :                                                        ^
^                                                                      ^
^ Returns true if current file could be opened and the new data wrote  ^
^                                                                      ^
^                                                                      ^
^ bool SaveAs(std::string file) :                                      ^
^                                                                      ^
^ Returns true if the file argument could be opened and the data wrote ^
^                                                                      ^
^                                                                      ^
^ unsigned int Size() :                                                ^
^                                                                      ^
^ Returns the number of elements in the data array                     ^
^                                                                      ^
^                                                                      ^
^ T& GetData(unsigned int location) :                                  ^
^                                                                      ^
^ Returns the data object at database location                         ^
^                                                                      ^
^                                                                      ^
^ T& operator[](unsigned int location) :                               ^
^                                                                      ^
^ Returns data object at location in database using array overload     ^
^                                                                      ^
^                                                                      ^
^ friend std::ostream& operator<<(std::ostream& os, Database<T> d)     ^
^                                                                      ^
^ returns ostream object containing all Database information          ^                                                                      ^
^                                                                      ^
^                                                                      ^
^ This code was finalized on the                                       ^
^                                                                      ^
^ This draft was written on Friday, 10th 2014                          ^
^                                                                      ^
^                                                                      ^
^                                                                      ^
^ Megatron_ - http://www.cplusplus.com/user/megatron_0/                ^
^                                                                      ^
/***********************************************************************/

Is there a good format which can be used? Is there anything I am missing? I'm not exactly sure what it's called, but any help will be appreciated.

[MiiNiPaa]

It is fine, but I suggest to look up Doxygen. It is useful tool for automatic generation of documentation from source code (specially written) comments.

In documentation you should also state what hapens if something is wrong:

/*
T& operator[](unsigned int location) :
Returns data object at location in database using array overload  <- nobody cares how.
        //What happens if location is larger than amoun of elements stored?
*/

Basicly look up some widely used documentation format.