Improved inline class / structures documentation

include/bastapir/bas/BasicTextParser.h

@@ -73,7 +73,7 @@ namespace bas
 		};
 
 		/// Construcst BasicTextParser object. Parameter |log| is required and you have to provide
-		/// error logging facility. You can also specify a dialect of BASIC dialect.
+		/// error logging facility. You can also specify a dialect of BASIC (48K or 128K).
 		BasicTextParser(ErrorLogging * log, Keywords::Dialect dialect = Keywords::Dialect_48K);
 
 		/// Sets options structure to the parser.
@@ -107,23 +107,37 @@ namespace bas
 
 		// MARK: - Private parser
 
+		/// Main parser function
 		bool doParse();
+
+		/// Parses one line in the document
 		bool doParseLine();
 
+		/// Parses line number at the beginning of line
 		bool doParseLineNumber();
+		/// Parses number in BASIC source code.
 		bool doParseNumber(bool as_binary);
+		/// Parses variables injected to the code (e.g. @SomeSymbol)
 		bool doParseVariable(bool is_line_begin);
+		/// Parses string in BASIC format
 		bool doParseString();
+		/// Parses back-slashes at the end of line.
 		bool doParseLineEscape(bool is_line_begin);
+		/// Parses keywords or characters in the rest of the document.
 		bool doParseKeywords(bool is_line_begin);
+		/// Parses REM comment
 		bool doParseREM();
 
 		/// Returns current BASIC line number.
 		U16 currentBasicLineNumber();
 
+		/// Captures range for name of variable
 		Tokenizer::Range captureVariableName();
+		/// Captures range for number
 		Tokenizer::Range captureNumber();
+		/// Captures range for hexadecimal number
 		Tokenizer::Range captureHexadecimalNumber();
+		/// Captures range for binary number
 		Tokenizer::Range captureBinaryNumber();
 
 
@@ -181,29 +195,46 @@ namespace bas
 
 		// MARK: - Members
 
+		/// Internal type for [name: variable] map.
 		typedef std::map<std::string, Variable> VarMap;
 
+		/// Logging facility.
 		ErrorLogging * _log;
+		/// Information about source file.
 		SourceFileInfo _sourceFileInfo;
 
+		/// Parser's options
 		Options _options;
+		/// Constants injected into the BASIC
 		VarMap _constants;
+		/// Variables & line number symbos.
 		VarMap _variables;
+		/// Keywords helper
 		Keywords _keywords;
 
+		/// String tokenizer
 		Tokenizer _tokenizer;
 
 		/// Private context structure.
 		struct CTX
 		{
+			/// Parser's pass. Must be 1 or 2
 			U16 pass = 0;
+			/// Current basic line number
 			U16 basicLineNumber = 0;
+			/// Last fully serialized line number
 			U16 basicLastLineNumber = 0;
+			/// Count of generated BASIC lines
 			U16 processedLines = 0;
+			/// Offset to `_output` marking beginning of current BASIC line
 			size_t beginLineBytesOffset = 0;
+			/// If true, then parser is at the beginning of line. In this state,
+			/// numeric sequence is interpreted as an exact line number.
 			bool lineBegin = true;
+			/// If true, then current line really generates BASIC program bytes.
 			bool lineContainsBytes = false;
 		};
+		/// Parser's context
 		CTX _ctx;
 
 		/// Returns new context for given pass.
@@ -213,7 +244,7 @@ namespace bas
 			return ctx;
 		}
 
-		/// Output bytes.
+		/// Output BASIC program bytes.
 		ByteArray _output;
 	};
 

include/bastapir/common/ErrorInfo.h

@@ -20,12 +20,22 @@
 
 namespace bastapir
 {
+	/// The `ErrorInfo` structure holds information about source file
+	/// where the error occured.
 	struct ErrorInfo
 	{
+		/// File name of source file.
+		/// If string is empty, then it's considered that structure doesn't
+		/// contain information about error.
 		std::string sourceFile;
+		/// Line where the error occured.
+		/// If value is equal to 0, then the line is not known.
 		size_t line 	= 0;
+		/// Column in the line, where the error occured.
+		/// If value is equal to 0, then the column is not known.
 		size_t column	= 0;
 
+		/// Returns true if structure contains a valid information.
 		bool hasInfo() const
 		{
 			return !sourceFile.empty();

include/bastapir/common/Path.h

@@ -22,11 +22,27 @@ namespace bastapir
 {
 	// MAR: - PathComponents
 
+	/// The `PathComponents` contains various information parsed
+	/// from full file or directory path.
 	struct PathComponents
 	{
+		/// Parent directory. Examples:
+		/// - If path is `/tmp/text.txt`, then directory is `/tmp`
+		/// - If path is `text.txt`, then directory is empty.
 		std::string directory;
+		/// File or directory name. Examples:
+		/// - If path is `/tmp/text.txt`, then file name  is `text.txt`
+		/// - If path is `text.txt`, then file name is `text.txt`.
 		std::string fileName;
+		/// File name without an extension. Examples:
+		/// - If path is `/tmp/text.txt`, then property is `text`
+		/// - If path is `text.txt`, then property is `text`.
+		/// - If path is `text.something.txt`, then property is `text.something`.
 		std::string fileNameNoExt;
+		/// Contains file extension. Examples:
+		/// - If path is `/tmp/text.txt`, then extension is `txt`
+		/// - If path is `text.txt`, then extension is `txt`.
+		/// - If path is `text.something.txt`, then extension is `txt`.
 		std::string extension;
 	};
 
@@ -44,7 +60,8 @@ namespace bastapir
 		const std::string path;
 
 		/// Returns PathComponents parsed from path stored in this object.
-		/// Note that function
+		/// Note that function doesn't cache components internally, so each call for components
+		/// will parse stored path.
 		PathComponents pathComponents() const;
 
 		/// Converts path in any format to platform specific path.
@@ -54,10 +71,7 @@ namespace bastapir
 		static PathComponents components(const std::string & any_path);
 
 		/// Contains directory separator used on current platform.
-		static const std::string directorySeparator;
-
-	private:
-
+		static const std::string directorySeparator;		
 	};
 
 } // bastapir

include/bastapir/common/SourceFile.h

@@ -33,6 +33,7 @@ namespace bastapir
 
 		/// Path to the file
 		std::string path;
+
 		/// Opening mode
 		Mode mode;
 

include/bastapir/common/Tokenizer.h

@@ -30,20 +30,24 @@ namespace bastapir
 		typedef std::string::const_iterator		iterator;
 		typedef std::string::difference_type	difference;
 
+		/// The `Range` structure contains `begin` & `end` of string.
 		struct Range
 		{
 			iterator begin;
 			iterator end;
 
+			/// Returns string between begin & end.
 			std::string content() {
 				return std::string(begin, end);
 			}
 
+			/// Returns true if `begin` is equal to `end`
 			bool empty() {
 				return begin == end;
 			}
 		};
 
+		/// The `State` structure contains a full state of tokenizer.
 		struct State
 		{
 			iterator	pos;
@@ -53,19 +57,25 @@ namespace bastapir
 			bool		updateLineEnd;
 		};
 
+		/// The `PositionInfo` structure contains an information about current
+		/// position in the source string.
 		struct PositionInfo
 		{
+			/// Current line number
 			size_t lineNumber = 0;
+			/// Offset at current line
 			size_t offsetAtLine = 0;
 		};
 
 		// MARK: - Constructor
 
+		/// Constructs Tokenizer object with optional error logging.
 		Tokenizer(ErrorLogging * log = nullptr);
 
 		// MARK: - Config
 
-		/// Assing (optional) error logging to the tokenizer.
+		/// Assing (optional) error logging to the tokenizer. Setting nullptr will reset
+		/// the currently assigned logger.
 		void setErrorLogging(ErrorLogging * logger);
 
 		/// Resets tokenizer for a new string processing.
@@ -81,33 +91,37 @@ namespace bastapir
 		void resetLine();
 
 		/// Changes behavior of isEnd() method, which will report end at the end of line.
-		/// In this mode, you need to call nextLine() to go to the next line
+		/// In this mode, you need to call nextLine() to move to the next line.
+		//
+		/// Note that this information is not a part of the `State` stucture.
 		void setStopAtLineEnd(bool stop);
 
-		/// Returns value previously set in `setStopAtLineEnd()`
+		/// Returns current mode of `isEnd()` method. If true, then Tokenizer reports
+		/// end at the end of current line.
 		bool isStopAtLineEnd() const;
 
 		/// Stores a whole state of tokenizer to structure
 		State state() const;
 
-		/// Restore previously stored state
+		/// Restore previously stored state.
 		void restoreState(const State & state);
 
-		/// Returns information about current position
+		/// Returns information about current position.
 		PositionInfo positionInfo() const;
 
 		/// Returns information about current position where `lineNumber` and `offsetAtLine` are increased by 1.
 		PositionInfo positionInfoForLog() const;
 
 		// MARK: - Walking over string
 
-		/// Returns true if tokenizer is at the end of line
+		/// Returns true if tokenizer is at the end of string or at the end of line. The behavior of this
+		/// method depends on mode changed in `setStopAtLineEnd()`.
 		bool isEnd() const;
 
 		/// Returns current position iterator.
 		iterator position() const;
 
-		/// Returns current limits. If `isStopAtLineEnd` is true then returns range of line, otherwise whole string.
+		/// Returns current limits. If `isStopAtLineEnd` is true then returns range of line, otherwise a whole string.
 		const Range & limit() const;
 
 		/// Returns char at current position and moves to the next position.
@@ -127,7 +141,7 @@ namespace bastapir
 		/// false if offset is out of range.
 		bool movePosition(difference offset = 1);
 
-		/// Go immediately to the next line. Returns false if we're at the end of processed string.
+		/// Go immediately to the next line. Returns false if we're at the end of string.
 		bool nextLine();
 
 		/// Returns range for current line.
@@ -139,9 +153,12 @@ namespace bastapir
 		/// Skip whitespace characters. The current position will end at first non-whitespace character or at the end.
 		bool skipWhitespace();
 
-		/// 
+		/// Skip characters while provided |match_function| returns true. The current position will end at the last
+		/// matched character.
 		bool skipWhile(int (*match_function)(int));
 
+		/// Iterates over the string, while |match_fucntion| returns false and stops iterations when function returns true.
+		/// The current position will end at the next to matched character.
 		bool searchFor(int (*match_function)(int));
 
 		// MARK: - Range capture
@@ -155,14 +172,25 @@ namespace bastapir
 		/// Returns current capture and then resets capture range to current position
 		Range captureAndReset();
 
+		// MARK: - Other
+
+		/// Prints debug information to stdout.
 		void _debugInfo() const;
 
 	private:
 
+		/// Returns true if position is at the end of string.
 		bool isRealEnd() const;
+
+		/// Returns character at current position and moves position to the next character.
+		/// This function ignores mode set in setStopAtLineEnd() method.
 		char realGetChar();
+
+		/// Returns character at current+offset position. If position is out of range, then returns 0.
+		/// This function ignores mode set in setStopAtLineEnd() method.
 		char realCharAt(difference offset) const;
 
+		/// Updates internal line end pointer.
 		void updateLineEnd();
 
 		bool	_stop_at_lf;

source/library/common/Tokenizer.cpp

@@ -137,7 +137,6 @@ namespace bastapir
 		if (!isEnd()) {
 			char c = *(_state.pos++);
 			if (c == 0) {
-				// TODO: throw an error
 				if (_log) {
 					_log->error("Tokenizer: NUL character detected in string.");
 				}
@@ -208,7 +207,6 @@ namespace bastapir
 				// Handle crappy MS-DOS & Descendants
 				c = realGetChar();
 				if (c != '\n') {
-					// TODO: throw an error, this is not right combination
 					if (_log) {
 						_log->error("Tokenizer: Invalid CR-LF sequence detected.");
 					}
@@ -253,7 +251,6 @@ namespace bastapir
 				return false;
 			}
 			if (!function(c)) {
-				// rollback, because received character did not pass test.
 				return true;
 			}
 			movePosition();