Changes between Version 31 and Version 32 of MapGuideCodingStandards

Timestamp:

Dec 8, 2012, 5:53:11 AM (11 years ago)

Author:

jng

Comment:

Extra notes about C++ documentation

MapGuideCodingStandards

@@ -6 +6 @@
 
 ||'''Revision'''||'''Date'''||'''Author'''||'''Comment'''||
+||1.6.2||9 Dec, 2012||Jackie Ng||More about C++ documentation||
 ||1.6.1||31 May, 2012||Jackie Ng||More about exception handling||
 ||1.6||July 7, 2008||Bruce Dechant||Initial public revision||
@@ -52 +53 @@
 == Documentation Standard ==
 
-=== .NET/C++ ===
-
-When you define a new public class, property, or method, you must follow the XML Doc standard.  Typing three slashes “///” just before a class/property/method declaration will bring up a skeleton XML Doc header in .NET, for C++ you will have to enter this.  You then simply need to add information in the different fields.  Note that if you fail to add the XML Doc header for .NET, the code may not compile (this is an option that we will enable for all our projects).
+=== .NET ===
+
+When you define a new public class, property, or method, you must follow the XML Doc standard.  Typing three slashes “///” just before a class/property/method declaration will bring up a skeleton XML Doc header in .NET. You then simply need to add information in the different fields.  Note that if you fail to add the XML Doc header for .NET, the code may not compile (this is an option that we will enable for all our projects).
 
 XML Doc Standard example:
@@ -74 +75 @@
 private bool CanIgnoreElement(Element element, string fileName)
 }}}
+
+=== C++ ===
+
+For C++, you can choose either to use the above .net XML doc standard or the [http://www.stack.nl/~dimitri/doxygen/manual.html doxygen ] standard.
+
+To facilitate the possibility of transferring such documentation fragments to wrapper proxy classes in the future, '''you should use the doxygen standard'''.
+
+If a given method is deprecated and should not be used in the future, please indicate so with the {{{\deprecated}}} doxygen directive. This will do two things:
+
+ 1. Cause the method in question to appear under the list of deprecated methods (and appear as deprecated under the class method documentation) in the API documentation that's generated by doxygen
+ 2. Allow for us in the future to convert these directives to {{{[ObsoleteAttribute]}}} in .net and {{{@Deprecated}}} in Java for their proxy classes.
 
 === General ===