Jump to content
  • Advertisement
Sign in to follow this  
SirLuthor

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.

If you intended to correct an error in the post then please contact us.

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 this post


Link to post
Share on other sites
Advertisement
Quote:
Original post by SirLuthor
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?

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 this post


Link to post
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_LOW
namespace 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 console
writing functions, this one returns a reference to a console, so
you 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() const
Writes a string to the console. As with all the other console
writing functions, this one returns a reference to a console, so
you 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!

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!