# Documentation Questions..

This topic is 4835 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

## Recommended Posts

Hello once again! I do seem to be posting a lot these days, I beg your tolerance, I'm just full to bursting with questions that I can't seem to find answers to [grin] Anyway, I figured that since I'm not very far at all on this latest rewrite of my core, I should document it, and build on the documentation as I go on. A few sources on the net mentioned NaturalDocs, which I then proceeded to set up, writing my batch files and setting them to run every build. Now, that's all well and good, it updates the documentation every time I re-compile, without a hitch. However, here's the deal. You people who have used ND know that when you write a function entry, it automatically picks up the function declaration, and plugs it into the documentation, at least in C++. However, for some reason, this is only happening about half the time? If someone who uses ND could explain why this is happening I would greatly appreciate it! Also, do people feel it is a bad thing to have to wade through pages of comments in a source file just to get to the code? Because I'd like to go fairly in detail with some of the notes, but I wouldn't want to do that if people think it impairs readability. Thanks!

##### Share on other sites
Quote:
 Original post by SirLuthorYou people who have used ND know that when you write a function entry, it automatically picks up the function declaration, and plugs it into the documentation, at least in C++. However, for some reason, this is only happening about half the time?

Can you give an example that does not work ?

Quote:
 Also, do people feel it is a bad thing to have to wade through pages of comments in a source file just to get to the code? Because I'd like to go fairly in detail with some of the notes, but I wouldn't want to do that if people think it impairs readability.

It's better to have too much comments than too few. If you want to get rid of the comments, you can easily delete them later on (i.e. via cpp). Another tool for documentation, doxygen, also creates a copy of the code with comments removed, which is included in the browseable documentation.

##### Share on other sites
Okay, here's an example of one source code file (I haven't commented the whole thing, only parts of it, I was messing around) which has a number of things that do and don't work. I've cut out a number of function defintions, because they don't pertain to the matter at hand (they're uncommented).

ASC-DebugConsole.cpp
/*File: ASC-DebugConsole.cpp  This file contains the definitions for all the ASC::Console member  functions that are not inline, plus the definition of the extern  console object, ASC::DEBUG_CONSOLE, that is used by the DCON1-3  #defines.  Last Updated:  Mon Aug 15 : 2005 by David*/#include <ASC-DebugConsole.hpp>#include <windows.h>#if defined ASC_CON_DEBUGCONSOLE && ASC_DEBUG_ >= ASCD_LOWnamespace ASC{	ASC::Console DEBUG_CONSOLE;}#endif// Namespace: ASC/*Class: Console  This class is responsible for maintaining a console which the end user  can send debug messages to and such.  Among the capabilites of the   Console class are:   - Native writing for most standard types   - Can be hooked up to a log, so it shows whatever is written to that   log.   - Can be attached to a log, so everything written to the console is   in turn written to that log.*/// DOES WORK:/*Constructor: Console();Allocates a console, retrieves the standard handles (input, output, error),and sets the title of it to 'Ascendancy Debug Console'.*/ASC::Console::Console() :outHandle(NULL),inHandle(NULL),errHandle(NULL){	if (!AllocConsole())	{		// throw a fatal error (and exit?)	}	outHandle = GetStdHandle(STD_OUTPUT_HANDLE);	inHandle = GetStdHandle(STD_INPUT_HANDLE);	errHandle = GetStdHandle(STD_ERROR_HANDLE);	SetConsoleTitle(T("Ascendancy Debug Console").c_str());}// DOES WORK:/*Destructor: ~Console();Frees the allocated console.*/ASC::Console::~Console(){	outHandle = NULL;	inHandle = NULL;	errHandle = NULL;	FreeConsole();}// DOES NOT WORK:/*Function: Console & operator << (const ASCSTRING & A_input)Writes a string to the console.  As with all the other consolewriting functions, this one returns a reference to a console, soyou can string '<<' operators together.Arguments:const ASCSTRING & input - The string that should be written to the console.Return value:A reference to the console object.*/ASC::Console & ASC::Console::operator << (const ASCSTRING & A_input){	ASCINT charsWritten = 0xFFFFFFFF;	if (!WriteConsole(outHandle, (const ASCVOID *)A_input.c_str(),		A_input.length(), &charsWritten, NULL))	{		// throw fat exception	}	if (charsWritten != A_input.length())	{		// throw other fat exception	}	return *this;}// DOES NOT WORK:/*Function: ASCVOID * const GetOutHandle() constWrites a string to the console.  As with all the other consolewriting functions, this one returns a reference to a console, soyou can string '<<' operators together.const ASCSTRING & input - The string that should be written to the console.A reference to the console object.*/ASCVOID * const ASC::Console::GetOutHandle() const{	return outHandle;}

Much obliged if someone could point out why it's not working for half of them, and working for the other half. Also, note that the function defeclaration doesn't show up as a tooltip either, like it does with the ones that do work.

Thanks!

1. 1
Rutin
34
2. 2
3. 3
4. 4
5. 5

• 12
• 14
• 9
• 9
• 9
• ### Forum Statistics

• Total Topics
633334
• Total Posts
3011410
• ### Who's Online (See full list)

There are no registered users currently online

×