From 0c3f6ae16e15167b44840e509413069ff528deda Mon Sep 17 00:00:00 2001 From: Lars Elgtvedt Susaas Date: Sat, 30 Mar 2024 07:06:00 +0100 Subject: [PATCH] Adding some missing comments (#96) --- libEDSsharp/Bridge.cs | 15 +- libEDSsharp/CanOpenNodeExporter.cs | 11 +- libEDSsharp/CanOpenNodeExporter_V4.cs | 18 +- libEDSsharp/DocumentationGen.cs | 61 ++++-- libEDSsharp/ExporterFactory.cs | 17 ++ libEDSsharp/IExporter.cs | 11 + libEDSsharp/NetworkPDOreport.cs | 23 ++- libEDSsharp/eds.cs | 277 +++++++++++++++++++++++--- 8 files changed, 373 insertions(+), 60 deletions(-) diff --git a/libEDSsharp/Bridge.cs b/libEDSsharp/Bridge.cs index f320313a..3e6a3570 100644 --- a/libEDSsharp/Bridge.cs +++ b/libEDSsharp/Bridge.cs @@ -33,10 +33,16 @@ You should have received a copy of the GNU General Public License namespace libEDSsharp { + /// + /// Converts between CanOpenXML and EDSsharp + /// public class Bridge { - - + /// + /// Convert from EDSsharp to CanOpenXML + /// + /// the eds data + /// CanOpenXML device containing data from eds public Device convert(EDSsharp eds) { eds.UpdatePDOcount(); @@ -269,6 +275,11 @@ public Xml2CSharp.Characteristic makecharcteristic(string name, string content) return cl; } + /// + /// Convert from CanOpenXML to EDSsharp + /// + /// CanOpenXML device + /// EDSsharp object containing data from dev public EDSsharp convert(Device dev) { EDSsharp eds = new EDSsharp(); diff --git a/libEDSsharp/CanOpenNodeExporter.cs b/libEDSsharp/CanOpenNodeExporter.cs index 4f13a71f..7de083bc 100644 --- a/libEDSsharp/CanOpenNodeExporter.cs +++ b/libEDSsharp/CanOpenNodeExporter.cs @@ -31,7 +31,9 @@ based heavily on the files CO_OD.h and CO_OD.c from CANopenNode which are namespace libEDSsharp { - + /// + /// Export .c and .h files for CanOpenNode v1-3 + /// public class CanOpenNodeExporter : IExporter { @@ -1347,7 +1349,12 @@ public static string GetValue() return method.Invoke(null, null) as string; } - + /// + /// Generates a valid C language variable name using input + /// + /// base name that will be used to make a variable name + /// the OD entry for the variable + /// protected string make_cname(string name,ODentry entry) { if (name == null) diff --git a/libEDSsharp/CanOpenNodeExporter_V4.cs b/libEDSsharp/CanOpenNodeExporter_V4.cs index 57ca7eca..c5e86043 100644 --- a/libEDSsharp/CanOpenNodeExporter_V4.cs +++ b/libEDSsharp/CanOpenNodeExporter_V4.cs @@ -68,7 +68,7 @@ public void export(string folderpath, string filename, string gitVersion, EDSsha /// /// Generate ODStorage, ODObjs, ODList, ODDefines and ODCnt entries /// - /// + /// EDS object private void Prepare(EDSsharp eds) { ODStorageGroups = new List(); @@ -380,11 +380,10 @@ private int Prepare_rec(ODentry od, string indexH, string varName, string group) /// /// Export the header file /// - /// - /// - /// - /// - /// + /// path to folder that will contain the file + /// filename + /// git version that will be added to file comment + /// data that contain the data that will be exported private void Export_h(string folderpath, string filename, string gitVersion, EDSsharp eds) { @@ -558,9 +557,10 @@ OD config structure /// /// Export the c file /// - /// - /// - /// + /// path to folder that will contain the file + /// filename + /// git version that will be added to file comment + /// data that contain the data that will be exported private void Export_c(string folderpath, string filename, string gitVersion, EDSsharp eds) { diff --git a/libEDSsharp/DocumentationGen.cs b/libEDSsharp/DocumentationGen.cs index 9b18e144..b5aef6a1 100644 --- a/libEDSsharp/DocumentationGen.cs +++ b/libEDSsharp/DocumentationGen.cs @@ -24,10 +24,18 @@ You should have received a copy of the GNU General Public License namespace libEDSsharp { + /// + /// Documentation generator + /// public class DocumentationGen { StreamWriter file = null; + /// + /// Generate html documentation + /// + /// where the documentation should be saved + /// data to generate the documentation from public void genhtmldoc(string filepath, EDSsharp eds) { @@ -96,8 +104,11 @@ public void genhtmldoc(string filepath, EDSsharp eds) } - - public void writeODentryhtml(ODentry od) + /// + /// Write a object dictionary html entry to file + /// + /// Object dictionary entry + void writeODentryhtml(ODentry od) { if (od.parent == null) { @@ -142,19 +153,32 @@ public void writeODentryhtml(ODentry od) } } - - public void write2linetablerow(string a,object b) + /// + /// Write a html table row with 2 elements to file + /// + /// element a + /// element b + void write2linetablerow(string a,object b) { if (b == null) b = ""; file.Write("{0}{1}", a, b.ToString()); } - - public void write2linetableheader(string a, object b) + /// + /// Write a html table header with 2 elements to file + /// + /// + /// + void write2linetableheader(string a, object b) { file.Write("{0}{1}",a,b.ToString()); } - + /// + /// Generate markup documentation + /// + /// where the documentation should be created + /// data to generate the documentation from + /// git version of this software public void genmddoc(string filepath, EDSsharp eds, string gitVersion) { file = new StreamWriter(filepath, false); @@ -253,8 +277,12 @@ Device Information file.Close(); } - - private void PrintPdoMd(EDSsharp eds, bool skipDisabled = false) + /// + /// Write a all PDO information in markup + /// + /// data containing the information + /// skip disabled PDOs + void PrintPdoMd(EDSsharp eds, bool skipDisabled = false) { var parameters = new SortedDictionary(); var mappings = new SortedDictionary(); @@ -361,8 +389,11 @@ private void PrintPdoMd(EDSsharp eds, bool skipDisabled = false) file.WriteLine(); } } - - private void PrintODentryMd(ODentry od) + /// + /// Write a object dictionary markup entry to file + /// + /// Object dictionary entry + void PrintODentryMd(ODentry od) { var descriptions = new List(); @@ -410,8 +441,12 @@ private void PrintODentryMd(ODentry od) file.WriteLine(string.Join("\n", descriptions)); } } - - private string PrintDataType(ODentry od) + /// + /// Returns the datatype of a object dictionary + /// + /// the object dictionary entry + /// datatype of the OD entry + string PrintDataType(ODentry od) { string dt = od.datatype.ToString(); if ((od.datatype == DataType.VISIBLE_STRING || od.datatype == DataType.UNICODE_STRING) diff --git a/libEDSsharp/ExporterFactory.cs b/libEDSsharp/ExporterFactory.cs index d4908fc2..56196964 100644 --- a/libEDSsharp/ExporterFactory.cs +++ b/libEDSsharp/ExporterFactory.cs @@ -1,14 +1,31 @@  namespace libEDSsharp { + /// + /// Factory for making different canopennode exporter + /// public static class ExporterFactory { + /// + /// CanOpenNode exporter types + /// public enum Exporter { + /// + /// CanOpenNode exporter v4 (latest) + /// CANOPENNODE_V4 = 0, + /// + /// CanOpenNode exporter for v1-3 (legacy) + /// CANOPENNODE_LEGACY = 1 } + /// + /// Returns exporter based on ex parameter + /// + /// what exporter version you want. Default is CANOPENNODE_LEGACY + /// A exporter public static IExporter getExporter(Exporter ex = Exporter.CANOPENNODE_LEGACY) { IExporter exporter; diff --git a/libEDSsharp/IExporter.cs b/libEDSsharp/IExporter.cs index 5f7a11ad..53b94b10 100644 --- a/libEDSsharp/IExporter.cs +++ b/libEDSsharp/IExporter.cs @@ -6,8 +6,19 @@ namespace libEDSsharp { + /// + /// Interface for exporting CanOpenNode OD files + /// public interface IExporter { + /// + /// Export file(s) + /// + /// Path to the folder that will contain the new files + /// base filename for the new files + /// version that will be saved to the file + /// The eds that will be exported + /// The object dictionary name void export(string folderpath, string filename, string gitVersion, EDSsharp eds , string odname="OD"); } } diff --git a/libEDSsharp/NetworkPDOreport.cs b/libEDSsharp/NetworkPDOreport.cs index 2f65b26d..a7318011 100644 --- a/libEDSsharp/NetworkPDOreport.cs +++ b/libEDSsharp/NetworkPDOreport.cs @@ -23,11 +23,18 @@ You should have received a copy of the GNU General Public License namespace libEDSsharp { + /// + /// Generate a PDO network report + /// public class NetworkPDOreport { StreamWriter file = null; - + /// + /// Generate a PDO network report + /// + /// where the doc should be saved + /// Data from the different nodes in the network public void gennetpdodoc(string filepath, List network) { @@ -320,15 +327,23 @@ public void gennetpdodoc(string filepath, List network) } - + /// + /// Write a html table row with 2 elements to file + /// + /// element a + /// element b public void write2linetablerow(string a, object b) { if (b == null) b = ""; file.Write("{0}{1}", a, b.ToString()); } - - public void write2linetableheader(string a, object b) + /// + /// Write a html table header with 2 elements to file + /// + /// + /// + void write2linetableheader(string a, object b) { file.Write("{0}{1}", a, b.ToString()); } diff --git a/libEDSsharp/eds.cs b/libEDSsharp/eds.cs index e5ef6dd3..a13b8de5 100644 --- a/libEDSsharp/eds.cs +++ b/libEDSsharp/eds.cs @@ -33,7 +33,9 @@ You should have received a copy of the GNU General Public License namespace libEDSsharp { - + /// + /// Object dictionary data types from CiA 301 + /// public enum DataType { UNKNOWN = 0, @@ -69,16 +71,43 @@ public enum DataType IDENTITY = 0x23, } - + /// + /// Object Dictionary object definitions from CiA 301 + /// public enum ObjectType { UNKNOWN = -1, + /// + /// An object with no data fields + /// NULL = 0, + /// + /// Large variable amount of data e.g. executable program code + /// DOMAIN =2, + /// + /// Denotes a type definition such as a BOOLEAN, UNSIGNED16, FLOAT and so on + /// DEFTYPE=5, + /// + /// Defines a new record type e.g. the PDO mapping structure at 21h + /// DEFSTRUCT=6, + /// + /// A single value such as an UNSIGNED8, BOOLEAN, FLOAT, INTEGER16, VISIBLE STRING etc. + /// VAR = 7, + /// + /// A multiple data field object where each data field is a + /// simple variable of the SAME basic data type e.g. array of UNSIGNED16 etc. + /// Sub-index 0 is of UNSIGNED8 and therefore not part of the ARRAY data + /// ARRAY = 8, + /// + /// A multiple data field object where the data fields may be any combination of + /// simple variables. Sub-index 0 is of UNSIGNED8 and sub-index 255 is of UNSIGNED32 and + /// therefore not part of the RECORD data + /// RECORD = 9, } @@ -91,19 +120,49 @@ public enum PDOMappingType @default=4, } + /// + /// Defines how the object can be changed from SDO + /// public enum AccessSDO { + /// + /// no access + /// no, + /// + /// read only access + /// ro, + /// + /// write only access + /// wo, + /// + /// read and write access + /// rw } + /// + /// Defines how the object can be changed from PDO + /// public enum AccessPDO { + /// + /// no access + /// no, + /// + /// TPDO access + /// t, + /// + /// RPDO access + /// r, + /// + /// TPDO and RPDO access + /// tr } @@ -120,13 +179,23 @@ public enum AccessSRDO /// public class CustomProperties { - public bool CO_disabled = false; // If true, object is completelly skipped by CANopenNode exporters, etc. + /// + /// If true, object is completelly skipped by CANopenNode exporters, etc. + /// + public bool CO_disabled = false; public string CO_countLabel = ""; public string CO_storageGroup = "RAM"; public bool CO_flagsPDO = false; public AccessSRDO CO_accessSRDO = AccessSRDO.no; + /// + /// Minimum length of a string that can be stored + /// public UInt32 CO_stringLengthMin = 0; + /// + /// Deep clone + /// + /// a deep clone public CustomProperties Clone() { return new CustomProperties @@ -139,7 +208,10 @@ public CustomProperties Clone() CO_stringLengthMin = CO_stringLengthMin }; } - + /// + /// Convert from XSD to EDS + /// + /// raw custom properties from XSD public void OdeXdd(property[] properties) { if (properties != null) @@ -164,7 +236,10 @@ public void OdeXdd(property[] properties) } } } - + /// + /// Convert custom properties from EDS to XSD + /// + /// XSD properties ready to use public property[] OdeXdd() { var props = new List(); @@ -240,6 +315,9 @@ public class DcfExport : EdsExport { } + /// + /// Section of info in EDS or DCF file + /// public class InfoSection { protected Dictionary section; @@ -337,7 +415,10 @@ public bool GetField(string name, string varname) return false; } - + /// + /// Returns a string that represents the current object. + /// + /// A string that represents the current object. public override string ToString() { string msg; @@ -356,7 +437,11 @@ public override string ToString() return msg; } - + /// + /// Write object to stream + /// + /// stream to write the data to + /// file type public void Write(StreamWriter writer, Filetype ft) { writer.WriteLine("[" + edssection + "]"); @@ -487,7 +572,10 @@ public virtual void Parse(Dictionary section) objectlist.Add(count, target); } } - + /// + /// Returns a string that represents the current object. + /// + /// A string that represents the current object. public override string ToString() { string msg; @@ -504,7 +592,10 @@ public override string ToString() return msg; } - + /// + /// Write object to stream + /// + /// stream to write the data to public void Write(StreamWriter writer) { writer.WriteLine("[" + edssection + "]"); @@ -548,7 +639,10 @@ public virtual void Parse(Dictionary section) } } - + /// + /// Returns a string that represents the current object. + /// + /// A string that represents the current object. public override string ToString() { string msg; @@ -565,7 +659,10 @@ public override string ToString() return msg; } - + /// + /// Write object to stream + /// + /// stream to write the data to public void Write(StreamWriter writer) { if(comments == null) @@ -619,13 +716,25 @@ public Dummyusage(Dictionary section) : this() } } + /// + /// FileInfo section as described in CiA 306 + /// public class FileInfo : InfoSection { // Only for internal usage, use Path.GetFileName(eds.projectFilename) instead. + /// + /// indicate the file name (according to OS restrictions) + /// [EdsExport] public string FileName=""; + /// + /// indicate the actual file version (Unsigned8) + /// [EdsExport] public string FileVersion=""; + /// + /// indicate the actual file revision (Unsigned8) + /// [EdsExport] public byte FileRevision;//=1 @@ -635,28 +744,48 @@ public class FileInfo : InfoSection public byte EDSVersionMajor;//=4.0 public byte EDSVersionMinor;//=4.0 + /// + /// indicate the version of the specification (3 characters) in the format x.y + /// [EdsExport] public string EDSVersion=""; - + /// + /// file description (max 243 characters) + /// [EdsExport(maxlength=243)] public string Description="";//= //max 243 characters - public DateTime CreationDateTime;// + /// + /// file creation time (characters in format hh:mm(AM|PM)), + /// [EdsExport] public string CreationTime=""; + /// + /// provide the date of file creation (characters in format mm-dd-yyyy) + /// [EdsExport] public string CreationDate=""; - + /// + /// name or a description of the file creator (max. 245 characters) + /// [EdsExport(maxlength = 245)] public string CreatedBy = "";//=CANFestival //max245 public DateTime ModificationDateTime;// + /// + /// time of last modification (characters in format hh:mm(AM|PM)) + /// [EdsExport] public string ModificationTime=""; + /// + /// date of the last file modification (characters in format mm-dd-yyyy) + /// [EdsExport] public string ModificationDate=""; - + /// + /// name or a description of the creator (max. 244 characters) + /// [EdsExport(maxlength = 244)] public string ModifiedBy="";//=CANFestival //max244 @@ -735,62 +864,122 @@ override public void Parse(Dictionary section, string sectionnam } } + /// + /// DeviceInfo section as described in CiA 306 + /// public class DeviceInfo : InfoSection { - + /// + /// vendor name (max. 244 characters) + /// [EdsExport] public string VendorName=""; + /// + /// unique vendor ID according to identity object sub-index 01h (Unsigned32) + /// [EdsExport] public string VendorNumber=""; - + /// + /// product name (max. 243 characters) + /// [EdsExport] public string ProductName=""; + /// + /// product code according to identity object sub-index 02h (Unsigned32) + /// [EdsExport] public string ProductNumber=""; + /// + /// product revision number according to identity object sub-index 03h (Unsigned32) + /// [EdsExport] public UInt32 RevisionNumber; + /// + /// indicate the supported baud rates (Boolean, 0 = not supported, 1=supported) + /// [EdsExport] public bool BaudRate_10 = false; + /// + /// indicate the supported baud rates (Boolean, 0 = not supported, 1=supported) + /// [EdsExport] public bool BaudRate_20 = false; + /// + /// indicate the supported baud rates (Boolean, 0 = not supported, 1=supported) + /// [EdsExport] public bool BaudRate_50 = false; + /// + /// indicate the supported baud rates (Boolean, 0 = not supported, 1=supported) + /// [EdsExport] public bool BaudRate_125 = false; + /// + /// indicate the supported baud rates (Boolean, 0 = not supported, 1=supported) + /// [EdsExport] public bool BaudRate_250 = false; + /// + /// indicate the supported baud rates (Boolean, 0 = not supported, 1=supported) + /// [EdsExport] public bool BaudRate_500 = false; + /// + /// indicate the supported baud rates (Boolean, 0 = not supported, 1=supported) + /// [EdsExport] public bool BaudRate_800 = false; + /// + /// indicate the supported baud rates (Boolean, 0 = not supported, 1=supported) + /// [EdsExport] public bool BaudRate_1000 = false; public bool BaudRate_auto = false; + /// + /// indicate the simple boot-up master functionality (Boolean, 0 = not supported, 1 = supported), + /// [EdsExport] public bool SimpleBootUpMaster; + /// + /// indicate the simple boot-up slave functionality (Boolean, 0 = not supported, 1 = supported), + /// [EdsExport] public bool SimpleBootUpSlave; - + /// + /// granularity allowed for the mapping on this device - + /// most of the existing devices support a granularity of 8 (Unsigned8; 0 - mapping not modifiable, 1-64 granularity) + /// [EdsExport] public byte Granularity = 8; + /// + /// Indicate the facility of dynamic variable generation. If the value is unequal to 0, the additional section DynamicChannels exists (CiA302 and CiA405) + /// [EdsExport] public bool DynamicChannelsSupported; [EdsExport] public byte CompactPDO; - + /// + /// indicate the facility of multiplexed PDOs. (Boolean, 0 = not supported, 1 = supported) + /// [EdsExport] public bool GroupMessaging; - + /// + /// indicate the number of supported receive PDOs. (Unsigned16) + /// [EdsExport] public UInt16 NrOfRXPDO; - + /// + /// indicate the number of supported transmit PDOs. (Unsigned16) + /// [EdsExport] public UInt16 NrOfTXPDO; - + /// + /// indicate if LSS functionality is supported (Boolean, 0 = not supported, 1 = supported) + /// [EdsExport] public bool LSS_Supported; @@ -1493,7 +1682,8 @@ public string Formatoctetstring(string value) /// /// Handle to the stream writer to write to /// File type being written - /// + /// OD type to write + /// module public void Write(StreamWriter writer, InfoSection.Filetype ft, Odtype odt= Odtype.NORMAL, int module=0) { @@ -1850,7 +2040,9 @@ public enum AccessType // for opened project file, but project is always saved as xdd_v1.1 // Filename within the FileInfo structure has only limited usage. public string projectFilename = ""; - // File name, when project is opened in xdd_v1.1 or project is saved + /// + /// File name, when project is opened in xdd_v1.1 or project is saved + /// public string xddfilename_1_1 = ""; // File names for exported files public string xddfilenameStripped = ""; @@ -2889,7 +3081,11 @@ static public byte ConvertToByte(string defaultvalue) return (Convert.ToByte(defaultvalue, Getbase(defaultvalue))); } - + /// + /// Convert two bytes into Uint16 (big endian) + /// + /// bytes to convert to Uint16, only the 2 first will be used + /// value of the 2 bytes combined (big endian) static public UInt16 ConvertToUInt16(byte [] bytes) { @@ -2900,7 +3096,11 @@ static public UInt16 ConvertToUInt16(byte [] bytes) return value; } - + /// + /// Try to convert a string to UInt16 + /// + /// string containing a number + /// the value or 0 if unable to read it static public UInt16 ConvertToUInt16(string defaultvalue) { if (defaultvalue == null || defaultvalue == "" ) @@ -2908,7 +3108,11 @@ static public UInt16 ConvertToUInt16(string defaultvalue) return (Convert.ToUInt16(defaultvalue, Getbase(defaultvalue))); } - + /// + /// Try to convert a string to UInt32 + /// + /// string containing a number + /// the value or 0 if unable to read it static public UInt32 ConvertToUInt32(string defaultvalue) { if (defaultvalue == null || defaultvalue == "" ) @@ -2916,7 +3120,11 @@ static public UInt32 ConvertToUInt32(string defaultvalue) return (Convert.ToUInt32(defaultvalue, Getbase(defaultvalue))); } - + /// + /// Return number base of a string (10 for desimal, 16 for hex and 8 for octal) + /// + /// a string that will be read to try to find its base number + /// 16 if hex, 8 if octal else 10 static public int Getbase(string defaultvalue) { @@ -3016,7 +3224,12 @@ public UInt32 GetNodeID(string input, out bool nodeidpresent) return 0; } - + /// + /// Try to get a OD entry + /// + /// the index + /// null if not found + /// true if found, false if not public bool tryGetODEntry(UInt16 index, out ODentry od) { od = null; @@ -3247,7 +3460,11 @@ public ODentry Getobject(string uniqueID) return null; } - + /// + /// Return the number of enabled objects + /// + /// Include subindexes in the counting + /// public int GetNoEnabledObjects(bool includesub=false) { int enabledcount = 0;