Voyager API Design Guide - Revision history

Cinc: Minor rewrite

2008-03-20T23:20:30Z

Minor rewrite

← Older revision		Revision as of 01:20, 21 March 2008
Line 66:		Line 66:
	The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.		The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.

	the next section is not true ~~anymore~~ [[User:Simpson 2\|Simpson 2]] 18:21, 20 March 2008 (CET) <br>		the next section is not true [[User:Simpson 2\|Simpson 2]] 18:21, 20 March 2008 (CET) <br>
	<strike>The reasons for the member name prefix is that the IDL compiler creates access macros with the method or member name prepended by an underscore only. If the members would not be prefixed, two classes within the entire class hierarchy could not have a method with the same name without resorting to the full method name which is built from the class name followed by the method name. </strike>		<strike>The reasons for the member name prefix is that the IDL compiler creates access macros with the method or member name prepended by an underscore only. If the members would not be prefixed, two classes within the entire class hierarchy could not have a method with the same name without resorting to the full method name which is built from the class name followed by the method name. </strike>
	Secondly using prefixes helps identifying the class group a method belongs to.		Secondly using prefixes helps identifying the class group a method belongs to.

Simpson 2: /* The Voyager API Classes and Interface Namespace */

2008-03-20T17:21:48Z

The Voyager API Classes and Interface Namespace

← Older revision		Revision as of 19:21, 20 March 2008
Line 66:		Line 66:
	The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.		The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.

	The reasons for the member name prefix is that the IDL compiler creates access macros with the method or member name prepended by an underscore only. If the members would not be prefixed, two classes within the entire class hierarchy could not have a method with the same name without resorting to the full method name which is built from the class name followed by the method name. Secondly using prefixes		the next section is not true anymore [[User:Simpson 2\|Simpson 2]] 18:21, 20 March 2008 (CET) <br>
	helps identifying the class group a method belongs to.		<strike>The reasons for the member name prefix is that the IDL compiler creates access macros with the method or member name prepended by an underscore only. If the members would not be prefixed, two classes within the entire class hierarchy could not have a method with the same name without resorting to the full method name which is built from the class name followed by the method name. </strike>
			Secondly using prefixes helps identifying the class group a method belongs to.

	Within a major part of the Voyager API,		Within a major part of the Voyager API,

Cla: /* The Voyager API Classes and Interface Namespace */ added comment on base class per API part

2007-08-26T11:02:03Z

The Voyager API Classes and Interface Namespace: added comment on base class per API part

← Older revision		Revision as of 13:02, 26 August 2007
Line 75:		Line 75:
	* API function names are prepended with a mixed case prefix, like Svc, Sys, Wp, e.g. SysCalculateNewUniverseSize()		* API function names are prepended with a mixed case prefix, like Svc, Sys, Wp, e.g. SysCalculateNewUniverseSize()
	* Prefix for helper functions (internal, maybe static, functions not visible to the world) needs to be defined		* Prefix for helper functions (internal, maybe static, functions not visible to the world) needs to be defined

			The class hierarchy of a major part of the Voyager API starts with the class XXXObject, where XXX is the all uppercase prefix of the API Part. Most class of this API part are derived from this base class.

	In addition to that the following rules apply to naming methods:		In addition to that the following rules apply to naming methods:

Cinc: Detailed reasons for method naming

2007-08-21T05:11:57Z

Detailed reasons for method naming

← Older revision		Revision as of 07:11, 21 August 2007
Line 66:		Line 66:
	The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.		The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.

	The reasons for the member name prefix is that the IDL compiler creates access macros with the method or member name prepended by an underscore only. If the members would not be prefixed, two classes within the entire class hierarchy could not have a method with the same name~~. The~~ name ~~clash problem~~ is ~~not completely solved~~ by the ~~member~~ name ~~prefix, but eased~~ a ~~lot~~.		The reasons for the member name prefix is that the IDL compiler creates access macros with the method or member name prepended by an underscore only. If the members would not be prefixed, two classes within the entire class hierarchy could not have a method with the same name without resorting to the full method name which is built from the class name followed by the method name. Secondly using prefixes
			helps identifying the class group a method belongs to.

	Within a major part of the Voyager API,		Within a major part of the Voyager API,

Cinc: Examples for naming. Some details.

2007-08-21T05:06:14Z

Examples for naming. Some details.

← Older revision		Revision as of 07:06, 21 August 2007
Line 69:		Line 69:

	Within a major part of the Voyager API,		Within a major part of the Voyager API,
	* class names are prepended with an all upper case prefix, like SVC, SYS, WP		* class names are prepended with an all upper case prefix, like SVC, SYS, WP, e.g. SYSObject
	* member names are prepended with a lower case prefix, like svc, sys, wp		* member names are prepended with a lower case prefix, like svc, sys, wp, e.g. sysQueryUniverseSize()
	* symbol names are prepended with an uppercase prefix with a trailing underscore, like SVC_, SYS_, WP_		* symbol names are prepended with an uppercase prefix with a trailing underscore, like SVC_, SYS_, WP_
	* API ~~helper~~ function names are prepended with a mixed case prefix, like Svc, Sys, Wp		* API function names are prepended with a mixed case prefix, like Svc, Sys, Wp, e.g. SysCalculateNewUniverseSize()
			* Prefix for helper functions (internal, maybe static, functions not visible to the world) needs to be defined

	In addition to that the following rules apply to naming methods:		In addition to that the following rules apply to naming methods:
	* where methods return a pointer to an object or data type		* where methods return a pointer to an object or data type
	** query methods return a pointer to original data that may not be altered or freed		** query methods return a pointer to original data that may not be altered or freed
	** get methods return a pointer to a copy of original data where the copy has to be released by the caller (destroy the object or free memory)		** get methods return a pointer to a copy of original data where the copy has to be released by the caller (destroy the object or free memory. A dedicated method to do that is ususally appropriate).

	== Extending the Voyager API ==		== Extending the Voyager API ==

Cla: /* The Voyager API Classes and Interface Namespace */ extended prefix rules, added methodd naming rules for get and query

2007-08-18T14:54:43Z

The Voyager API Classes and Interface Namespace: extended prefix rules, added methodd naming rules for get and query

← Older revision		Revision as of 16:54, 18 August 2007
Line 62:		Line 62:

	Cinc: this part must be reviewed and should be considered a proposal only.		Cinc: this part must be reviewed and should be considered a proposal only.
			<br>cla: all of this document must be considered as a proposal :-)

	The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.		The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.
Line 68:		Line 69:

	Within a major part of the Voyager API,		Within a major part of the Voyager API,
	* class names are prepended with ~~a mixed~~ case prefix, like ~~Svc~~, ~~Sys~~, Wp		* class names are prepended with an all upper case prefix, like SVC, SYS, WP
	* member names are prepended with a lower case prefix, like svc, sys, wp		* member names are prepended with a lower case prefix, like svc, sys, wp
	* ~~symbols~~ are prepended with an uppercase prefix with a trailing underscore, like SVC_, SYS_, WP_		* symbol names are prepended with an uppercase prefix with a trailing underscore, like SVC_, SYS_, WP_
			* API helper function names are prepended with a mixed case prefix, like Svc, Sys, Wp

			In addition to that the following rules apply to naming methods:
			* where methods return a pointer to an object or data type
			** query methods return a pointer to original data that may not be altered or freed
			** get methods return a pointer to a copy of original data where the copy has to be released by the caller (destroy the object or free memory)

	== Extending the Voyager API ==		== Extending the Voyager API ==

Ktk at 09:19, 31 July 2007

2007-07-31T09:19:21Z

← Older revision		Revision as of 11:19, 31 July 2007
Line 1:		Line 1:
			[[Category:Voyager]]
	This page contains a first draft for the Design and Implementation Guide for the Voyager API. Please note that the codename Voyager will not appear in the resulting document anylonger, once this document has reached the final version.		This page contains a first draft for the Design and Implementation Guide for the Voyager API. Please note that the codename Voyager will not appear in the resulting document anylonger, once this document has reached the final version.

Cinc: /* Extending the Voyager API */

2007-07-30T21:07:32Z

Extending the Voyager API

← Older revision		Revision as of 23:07, 30 July 2007
Line 72:		Line 72:

	== Extending the Voyager API ==		== Extending the Voyager API ==

			''<to be edited>''

	The following tasks are to be processed when suggesting an extension to the Voyager API:		The following tasks are to be processed when suggesting an extension to the Voyager API:
	* document new functionality		* document new functionality
Line 90:		Line 93:

	For the steps marked with (*) it may make sense to discuss the existing results with the maintainers of the API, to make sure that the testcase implementation already meets all requirements and design and implementation rules.		For the steps marked with (*) it may make sense to discuss the existing results with the maintainers of the API, to make sure that the testcase implementation already meets all requirements and design and implementation rules.


	== Accepting contributions for the Voyager API ==		== Accepting contributions for the Voyager API ==

Cinc: /* Accepting contributions for the Voyager API */

2007-07-30T21:06:57Z

Accepting contributions for the Voyager API

← Older revision		Revision as of 23:06, 30 July 2007
Line 93:		Line 93:

	== Accepting contributions for the Voyager API ==		== Accepting contributions for the Voyager API ==

			''<to be edited>''

	When a proposal for an extension is being sent to the maintainer team, the team will determine the maintainer for that extension (not necessarily one of the team). The proposal can be sent in as an idea only, when asking for expertise and feedback, or already as a fully implemented extension.		When a proposal for an extension is being sent to the maintainer team, the team will determine the maintainer for that extension (not necessarily one of the team). The proposal can be sent in as an idea only, when asking for expertise and feedback, or already as a fully implemented extension.

Cinc: /* The Voyager API Classes and Interface Namespace */

2007-07-30T21:02:40Z

The Voyager API Classes and Interface Namespace

← Older revision		Revision as of 23:02, 30 July 2007
Line 59:		Line 59:

	== The Voyager API Classes and Interface Namespace ==		== The Voyager API Classes and Interface Namespace ==

			Cinc: this part must be reviewed and should be considered a proposal only.

	The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.		The class names and the names of the classes' methods and members are prefixed by a tag identifying the major part of the API.

Line 67:		Line 70:
	* member names are prepended with a lower case prefix, like svc, sys, wp		* member names are prepended with a lower case prefix, like svc, sys, wp
	* symbols are prepended with an uppercase prefix with a trailing underscore, like SVC_, SYS_, WP_		* symbols are prepended with an uppercase prefix with a trailing underscore, like SVC_, SYS_, WP_


	== Extending the Voyager API ==		== Extending the Voyager API ==