Archived

This topic is now archived and is closed to further replies.

Jumpster

Abnormal question about documentation...

Recommended Posts

Does anybody know of a utility or program that can be used to take by source files and create a Help file for all of the classes I have written in C++? I have to create ~80+ classes as my "Bricks" and "Mortar" before I can even really begin creating my foundation classes (Graphics engine, sound engine etc.) What I have found is that now I am nearly 40+ classes complete and I find my brain can''t remember all of the specific details of each class I have created (what''s virtual, pure virtual, const etc.) without having to look it up in the source files (if I can remember which file it is in). I want to be able to take my classes, create a Windows Help file and link that file to my VS6 help files so I can just press F1 to refresh my memory. I realize that the VS6 has the Class Structure window pane thingy but with all of the WINDOWS crap, my stuff is still difficult to find and using the Database Defintions Option thingy doesn''t seem to find what I am looking for most of the time. I have various object diagrams and such but flipping through a countless number of pages is very time consuming too. Not to mention, the actual implementation details are not listed on those diagrams either. Thank goodness I do comment the code the way I do or I would be utterly and completely lost! Any suggestions in this matter would be appreciated. Regards, Jumpster

Share this post


Link to post
Share on other sites
quote:

http://www.doc-o-matic.com



I tried that one. I don't like it for a couple of reasons.

1) It's a Pre-Release version. Because it is a pre-release version, there is *NO* documentation on it. *NO* examples etc. I don't mind using Pre-Release anything, Heck, someone's got to test it, but I am having too many problems getting it to work.

2) An even more compelling reason for me not to use it is: it seems to *require* me to change my commenting style. Below is an example of my commenting style and the program creates gibberish:


/*
***************************************************************************************************
***************************************************************************************************
***
*** File Name: WFBitLists.h
*** Description: Header file to define the WF_BITLIST class and related code.
*** Author: J.W. Heikkila, Jr.
***
*** Copyright:
***
*** Confidential and Proprietary Source Code for
*** Wild-Fire Gaming Systems, Inc.
*** 437 Jamesway, Marion, Ohio 43302
***
*** Revisions:
***
*** 08/30/2000 - JWH - Original version.
***
*** Copyright (c) 2000, Wild-Fire Gaming Systems, Inc. All rights reserved.
***
***************************************************************************************************
***************************************************************************************************
*/

#ifndef _WFBITLISTS_H_
#define _WFBITLISTS_H_


/*
***************************************************************************************************
***************************************************************************************************
***
*** Class Name: WF_BITLIST
*** Description: This class is used to track individual bits within a list.
*** Author: J.W. Heikkila, Jr.
***
***************************************************************************************************
***************************************************************************************************
*/
typedef class WF_BITLIST
{

protected:

enum BITS_IN_BYTE { _NUM_BITS_ = 8 };

// Data definitions...
int BitCount;
int Elements;
unsigned int* Bits;


public:

// Constructor/Destructor definitions...
WF_BITLIST( int num = 32 );
WF_BITLIST( const WF_BITLIST& source );
virtual ~WF_BITLIST();


public:

// Method definitions...
virtual void __fastcall ClearAll();
virtual int __fastcall CountElements() const;
virtual int __fastcall CountBits() const;


} WF_BITLIST, *WF_BITLISTptr, **WF_BITLISTlist;


#endif // _WFBITLISTS_H_



/*
***************************************************************************************************
***************************************************************************************************
***
*** Function Name: WF_BITLIST::WF_BITLIST()
*** Description: This is the default WF_BITLIST:: constructor. It simply initializes the
*** class data values.
***
*** Parameters: const int num = 32 - [in] - The number of bits to create in the bitlist.
*** Defaults to 32. The number passed in should be
*** a multiple of 32 (4bytes * 8bits). If it is not,
*** then this method will up the count to the next
*** multiple of 32.
***
*** Returns: By default, it will return a new instance of the object.
***
*** Author: J.W. Heikkila, Jr.
***
***************************************************************************************************
***************************************************************************************************
*/
WF_BITLIST::WF_BITLIST( int num )
{
// Bounds checking... Default to 32 bits...
if ( num<=0 ) { num = 32; }

//**************************************************************************
// When determining a modulus with a power of 2 (32 in the case below)
// an optimization can be made to AND the number with the power of 2 - 1.
// In effect: int mod = num % 32;
// is optimized to: int mod = num & 31;
int mod = num & 31;

// Is it already multiple of 32...?
if (0 != mod) { num += (32 - mod); }


//*****************************************************************************
// Another optimization is when dividing a number by a power of two. The
// optimization can be made by right shifting (>>) the number with the bit
// count required to achieve the desired power of two.
// In effect: int Element = ((num / sizeof(unsigned int)) / _NUM_BITS_);
// is optimized to: int Element = ((num >> 2) >> 3); // Divide by four then by eight
// further optimized to: int Element = num >> 5;
//
// Calculate the number of Array Elements...
Elements = (num >> 5);
Bits = new unsigned int[Elements];
BitCount = num - 1;

ClearAll();
}




I have also checked out George/GUI code documentor, but it is difficult to get working at all, not to mention it seems to be a hodge-podge piece of software.

I really like the Doc-o-matic's output style, which is apparently customizable, but if it don't recognize my tags and comments properly it's of no use to me.

Any other suggestions?

Regards,
Jumpster

P.S. For those that are interested, this entire class can be found at TCS's site (glVelocity) in the Code Archive Section (BitList Class).


Edited by - Jumpster on November 1, 2000 12:37:59 PM

Share this post


Link to post
Share on other sites