Thread: Checking documentation is suitable

  1. #1
    Registered User awsdert's Avatar
    Join Date
    Jan 2015
    Posts
    937

    Checking documentation is suitable

    I've just started splitting my code into multiple files and thought I would check if the comments I'm using are suitable enough for documenting my code, I welcome all suggestions here.
    Here's the first one that I don't intend to change the API on
    Code:
    typedef struct space {
    	size_t given;
    	void *block;
    } space_t;
    
    /** @brief Memory allocater, usually via malloc, realloc & free
     * @param err Thread safe passback of encountered errors, in the event
     * malloc or realloc fail then this will be filled with whatever errno
     * holds at that time
     * @param space Desitination of allocated memory, initialise with {0}
     * @param want Amount of memory you want
     * @param dir Direction to restraint allocation to, see below defines
     * @return allocated memory or NULL, nothing in space parameter will be
     * overwritten if memory failes to be retrieved, if freed will be
     * cleared
     * @example if ( !(txt = change_space(
     * &ret, &text, BUFSIZ, 0 )) ) {...}
    **/
    void* change_space( int *err, space_t *space, size_t want, int dir );
    #define need_space( err, space, want )\
    	change_space( err, space, want, 0 )
    #define more_space( err, space, want )\
    	change_space( err, space, want, 1 )
    #define less_space( err, space, want )\
    	change_space( err, space, want, -1 )
    #define free_space( err, space )\
    	change_space( err, space, 0, 0 )
    	
    typedef size_t node_t;
    typedef struct nodes {
    	node_t count;
    	node_t total;
    	space_t space;
    } nodes_t;
    
    /** @brief Node allocater, passes over to change_space() after doing
     * calculations
     * @param err Thread safe passback of encountered errors, in the event
     * malloc or realloc fail then this will be filled with whatever errno
     * holds at that time
     * @param nodes Desitination of allocated memory, initialise with {0}
     * @param Nsize size of each node, sizeof(T) is best practice here
     * @param want Number of nodes you want
     * @param dir Direction to restraint allocation to, see below defines
     * @return allocated memory or NULL, nothing in nodes parameter will be
     * overwritten if memory failes to be retrieved, if freed will be
     * cleared
     * @example if ( !(txt = change_space(
     * &ret, &text, sizeof(wchar_t), BUFSIZ, 0 )) ) {...}
    **/
    void* change_nodes(
    	int *err, nodes_t *nodes, size_t Nsize, size_t want, int dir );
    #define need_nodes( T, err, nodes, want )\
    	(T*)change_nodes( err, nodes, sizeof(T), want, 0 )
    #define more_nodes( T, err, nodes, want )\
    	(T*)change_nodes( err, nodes, sizeof(T), want, 1 )
    #define less_nodes( T, err, nodes, want )\
    	(T*)change_nodes( err, nodes, sizeof(T), want, -1 )
    #define free_nodes( T, err, nodes )\
    	(T*)change_nodes( err, nodes, sizeof(T), 0, 0 )

  2. #2
    Registered User awsdert's Avatar
    Join Date
    Jan 2015
    Posts
    937
    Alright I uploaded the full project to git now so issues with documentation/comments can be shoved there
    GitHub - awsdert/gasp: Game Assistive tech for Solo Play

  3. #3
    Registered User awsdert's Avatar
    Join Date
    Jan 2015
    Posts
    937
    Well I hit a stumbling block in my little project, before I start a thread about it I'd like the people who are actually interested to go to the github page and raise any issues they have with the code comments (or lack thereof) because I don't wanna be complained at so shortly after being reminded that I'm poor at documenting & commenting I've already commented a few, I think the rest are self explanatory with the function names but just in case I still want peops to tell me if they find anything confusing enough to need comments

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. No suitable constructor?!?!
    By adam.morin in forum C++ Programming
    Replies: 5
    Last Post: 02-18-2011, 06:42 AM
  2. Is C/C++ suitable for an econ student?
    By pantera in forum General Discussions
    Replies: 19
    Last Post: 05-04-2010, 08:29 AM
  3. Suitable Compiler?
    By Carola in forum Windows Programming
    Replies: 4
    Last Post: 08-25-2009, 02:01 AM
  4. Which OS is more suitable for programming?
    By Utopus in forum Tech Board
    Replies: 32
    Last Post: 06-27-2007, 05:39 PM

Tags for this Thread