Comments on my documentation

**std10093** · 11-06-2012

A project about handling a BST with generic type of values.
I am going to provide a small of my header file(which i might divide it into two but that's not the point now).

File: treeGenericManagement.h

Code:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/* Typedef pointer to BST                                               */
typedef struct tnode *Treeptr;

/* Struct of BST                                                        */
typedef struct tnode {
  Treeptr left;
  Treeptr parent;
  Treeptr right;
  void* value;
} Treenode;

/* Inserts value into the BST.The function will enclose value into a    */
/* node. A function that defines comparison between elements is needed  */
/* @param p :  pointer to BST                                           */
/* @param v :  value that is to be inserted                             */
/* @param sizeOfType :  the size of element's type that are handled     */
/* @param compare :  function pointer to the function that will define  */
/* comparison between elements.                                         */
/* Returns  :  pointer to the new BST, after insertion                  */
/* About the parameter(function pointer) compare                        */
/* Compares two elements                                                */
/* @param arg1 :  first element to be compared                          */
/* @param arg2 :  second element to be compared                         */
/* Returns     :
/* In case that arg1 precedes arg2, -1 is returned                      */
/* In case they are equal, return zero                                  */
/* Else, return 1                                                       */

Treeptr addtree(Treeptr p, void* v ,int sizeOfType,int (*compare)
     ( void* arg1, void* arg2));



/* Performs an operation specified by the user in BST                   */
/* @param p :  pointer to BST                                           */
/* @param operation :  function pointer to the operation that is going  */
/* to be applied in BST                                                 */

void nodesGeneric(Treeptr p,void(*operation)(void*));



/* Find minimum element in BST                                          */
/* @param p :  pointer to BST                                           */
/* Returns  :  pointer to the node holding the minimum element          */
/* Notice that the return value is NULL, if BST has no nodes            */

Treeptr minnode(Treeptr p);



/* Find successor node x                                                */
/* @param x :  pointer to the node of BST we are interested in          */
/* Returns  :  pointer to the successor of node x                       */

Treeptr successor(Treeptr x);



/* Search if value exist in BST                                         */
/* @param p :  pointer to BST                                           */
/* @param v :  value that we search for                                 */
/* Returns  :  a pointer to the node holding the value.If value does    */
/* not exist,return NULL                                                */

Treeptr treesearch(Treeptr p, void* v);



/* Deletes value(if exists) from the BST.                               */
/* A function that defines comparison between elements is needed        */
/* @param p :  pointer to BST                                           */
/* @param v :  value that is to be inserted                             */
/* @param sizeOfType :  the size of element's type that are handled     */
/* @param compare :  function pointer to the function that will define  */
/* comparison between elements.                                         */
/* Returns  :  pointer to the new BST, after insertion                  */
/* About the parameter(function pointer) compare                        */
/* Compares two elements                                                */
/* @param arg1 :  first element to be compared                          */
/* @param arg2 :  second element to be compared                         */
/* Returns     :
/* In case that arg1 precedes arg2, -1 is returned                      */
/* In case they are equal, return zero                                  */
/* Else, return 1                                                       */

Treeptr deletenode(Treeptr p ,void* v,int sizeOfType , int (*operation)(void* arg1,void* arg2))

Any comment about it would be highly appreciated

**phantomotap** · 11-06-2012

typedef struct tnode *Treeptr;

Eeeeww!

Struct of BST

Redundant comment is redundant.

Inserts value into the BST.

Why is the function called `addtree'?

A function that defines comparison between elements is needed

Redundant comment is redundant.

pointer to the new BST, after insertion

The "BST" is duplicated and then a node is inserted?

Or the "BST" is modified and the existing "BST" is returned?

You need to consider this and potentially modify "Inserts value into the BST." accordingly.

/* About the parameter(function pointer) compare */
/* Compares two elements */
/* @param arg1 : first element to be compared */
/* @param arg2 : second element to be compared */
/* Returns :
/* In case that arg1 precedes arg2, -1 is returned */
/* In case they are equal, return zero */
/* Else, return 1 */

Consider a `typedef' for the function pointer so that you may document this facility separately allowing you to "reuse" good documentation of the `typedef'.

Performs an operation specified by the user in BST

What is the purpose of this facility?

Why don't I just call `operation' directly?

Is this a "visitor" type facility? Why does it have such a bad name?

If this a "callback" called for every node following in the "BST"? Why do the names not reflect that mechanism?

Search if value exist in BST

How?

Your comparison function and search function do not process the size of a "value".

Am I not allowed to add "values" of different length? Or am I just required to store the length of a "value" within the "value"?

Soma

**std10093** · 11-06-2012