Comments on my documentation

This is a discussion on Comments on my documentation within the C Programming forums, part of the General Programming Boards category; A project about handling a BST with generic type of values. I am going to provide a small of my ...

  1. #1
    SAMARAS std10093's Avatar
    Join Date
    Jan 2011
    Location
    Nice, France
    Posts
    2,681

    Comments on my documentation

    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
    Last edited by std10093; 11-06-2012 at 03:25 PM.

  2. #2
    Master Apprentice phantomotap's Avatar
    Join Date
    Jan 2008
    Posts
    4,257
    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

  3. #3
    SAMARAS std10093's Avatar
    Join Date
    Jan 2011
    Location
    Nice, France
    Posts
    2,681
    Quote Originally Posted by phantomotap View Post
    Eeeeww!
    You do not like the typedef of tree pointer.Maybe i am getting close to that opinion.typedef'ed pointer prones to error



    Quote Originally Posted by phantomotap View Post
    Redundant comment is redundant.
    Agree about all the redundants comments you spotted.

    Quote Originally Posted by phantomotap View Post
    Why is the function called `addtree'?
    I did not select the names of the functions.However i will agree with you.

    Quote Originally Posted by phantomotap View Post
    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.
    In my opinion your best point.Will change it.Thank you very much for this and your time.

    Quote Originally Posted by phantomotap View Post
    Consider a `typedef' for the function pointer so that you may document this facility separately allowing you to "reuse" good documentation of the `typedef'.
    I will have it in the back of my head for next time.

    Quote Originally Posted by phantomotap View Post

    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"?
    All the elements of tree are going to be of the same data type.Will point it out too.
    Quote Originally Posted by phantomotap View Post
    Soma
    Samaras

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. STL documentation?
    By Aisthesis in forum C++ Programming
    Replies: 1
    Last Post: 01-26-2010, 09:55 AM
  2. Documentation
    By marQade in forum C++ Programming
    Replies: 15
    Last Post: 02-22-2008, 06:05 PM
  3. C++ API Documentation
    By Ari.Patrick in forum C++ Programming
    Replies: 4
    Last Post: 06-12-2006, 05:08 AM
  4. dev cpp documentation
    By sanchezero in forum Game Programming
    Replies: 2
    Last Post: 06-18-2002, 02:32 PM
  5. Documentation Help!
    By WinAmp in forum C Programming
    Replies: 8
    Last Post: 05-19-2002, 03:21 AM

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21