Debian Codegraph @

external/api-doc-tools/mdoc/Mono.Documentation/Updater/Formatters/JsUsageFormatter.cs

raw
1 using System.Linq;
2 using System.Text;
3 using Mono.Cecil;
4 using Mono.Documentation;
5 using Mono.Documentation.Updater;
6 using Mono.Documentation.Util;
7
8 namespace mdoc.Mono.Documentation.Updater.Formatters
9 {
10 public class JsUsageFormatter : JsFormatter
11 {
12 public override string Language => "JavaScript (usage)";
13
14 protected override string GetPropertyDeclaration(PropertyDefinition property)
15 {
16 bool getVisible = property.GetMethod != null && property.GetMethod.IsPublic;
17 bool setVisible = property.SetMethod != null && property.SetMethod.IsPublic;
18 var method = property.SetMethod ?? property.GetMethod;
19
20 // https://github.com/mono/api-doc-tools/issues/133
21 // var [property value type, camel-cased] = [typename, camel-cased].[property name, camel-cased];
22 // [typename, camel-cased].[property name, camel-cased] = [property value type, camel-cased];
23 // Static properties
24 // var [property value type, camel-cased] = [typename].[property name, camel-cased];
25 // [typename].[property name, camel-cased] = [property value type, camel-cased];
26 var buf = new StringBuilder();
27 var propertyValueType = CamelCase(GetName(property.PropertyType));
28 var propertyName = DocUtils.GetPropertyName(property, NestedTypeSeparator);
29 var propertyNameCamelCased = CamelCase(propertyName);
30 var typeName = GetName(property.DeclaringType);
31 if (!method.IsStatic)
32 typeName = CamelCase(typeName);
33
34 if (getVisible)
35 {
36 buf.Append("var ");
37 buf.Append(propertyValueType);
38 buf.Append(" = ");
39 buf.Append(typeName);
40 buf.Append(".");
41 buf.Append(propertyNameCamelCased);
42 buf.Append(";");
43 }
44
45 if (setVisible)
46 {
47 if (getVisible)
48 buf.Append(GetLineEnding());
49
50 buf.Append(typeName);
51 buf.Append(".");
52 buf.Append(propertyNameCamelCased);
53 buf.Append(" = ");
54 buf.Append(propertyValueType);
55 buf.Append(";");
56 }
57 return buf.ToString();
58 }
59
60 protected override string GetTypeDeclaration(TypeDefinition type)
61 {
62 var buf = new StringBuilder();
63
64 if (type.IsEnum)
65 {
66 // var value = [fully qualified type].[camel-cased name of first enum value];
67 var firstElement = type.GetMembers().Skip(1).First();//skip "__value element"
68
69 buf.Append("var value = ");
70 buf.Append(ProcessFullName(type.FullName));
71 buf.Append(".");
72 buf.Append(CamelCase(firstElement.Name));
73 return buf.ToString();
74 }
75 if (type.IsValueType)
76 {
77 //Structures: Windows Runtime structures are objects in JavaScript.
78 // If you want to pass a Windows Runtime structure to a Windows Runtime method,
79 // don't instantiate the structure with the new keyword. Instead, create an object
80 // and add the relevant members and their values. The names of the members should be in camel case:
81 // SomeStruct.firstMember.
82
83 // var [struct name, camel cased] = {
84 // [fieldname, came cased] : /* Your value */
85 buf.Append("var ");
86 buf.Append(CamelCase(GetName(type)));
87 buf.Append(" = {");
88 buf.Append(GetLineEnding());
89 buf.Append(string.Join("," + GetLineEnding(),
90 type.Fields.Select(i => CamelCase(i.Name) + " : /* Your value */")));
91 buf.Append(GetLineEnding());
92 buf.Append("}");
93 return buf.ToString();
94 }
95 if (DocUtils.IsDelegate(type))
96 {
97 // var [delegateName, camel-cased]Handler = function([parameter name list, camel cased]){
98 // /* Your code */
99 // }
100 MethodDefinition invoke = type.GetMethod("Invoke");
101 buf.Append("var ");
102 buf.Append(CamelCase(GetName(type)));
103 buf.Append("Handler = function(");
104 AppendParameters(buf, invoke, invoke.Parameters);
105 buf.Append("){");
106 buf.Append(GetLineEnding());
107 buf.Append("/* Your code */");
108 buf.Append(GetLineEnding());
109 buf.Append("}");
110 return buf.ToString();
111 }
112
113 var publicConstructor = GetConstructor(type);
114 return GetDeclaration(publicConstructor);
115 }
116
117 protected override string GetMethodDeclaration(MethodDefinition method)
118 {
119 var buf = new StringBuilder();
120
121 if (IsAsync(method))
122 {
123 // Async Methods
124 // (For static methods, use the fully-qualified class name. For non-static,
125 // use the class name without qualification and camel-cased.)
126 // [fully qualified type name].[camel-cased method name]([parameter names]).done( /* Your success and error handlers */ );
127 var typeName = CamelCase(GetName(method.DeclaringType));
128 if (method.IsStatic)
129 typeName = ProcessFullName(method.DeclaringType.FullName);
130
131 buf.Append(typeName);
132 buf.Append(".");
133 buf.Append(GetMethodName(method));
134 buf.Append("(");
135 AppendParameters(buf, method, method.Parameters);
136 buf.Append(").done( /* Your success and error handlers */ )");
137
138 return buf.ToString();
139 }
140
141 // For static and non-static method generate different signatures:
142 // 1) Non-static
143 // Usage (not void)
144 // var [return type, camel-cased] = [class-name, camel-cased].[method-name, camel-cased]([parameter name list]);
145 // Usage (void)
146 // [class-name, camel-cased].[method-name, camel cased]([parameter name list]);
147 // 2) Static
148 // Usage (not void)
149 // var [return type, camel-cased] = [fully-qualified class-name].[method-name, camel-cased]([parameter n
150 // Usage (void)
151 // [fully-qualified class name].[method-name, camel cased]([parameter name list]);
152 if (method.ReturnType != null && ProcessFullName(method.ReturnType.FullName) != Consts.VoidFullName)
153 {
154 buf.Append("var ");
155 buf.Append(CamelCase(GetName(method.ReturnType)));
156 buf.Append(" = ");
157 }
158 var className = method.IsStatic ? ProcessFullName(method.DeclaringType.FullName) : CamelCase(GetName(method.DeclaringType));
159 buf.Append(className);
160 buf.Append(".");
161 buf.Append(CamelCase(method.Name));
162 buf.Append("(");
163 AppendParameters(buf, method, method.Parameters);
164 buf.Append(")");
165
166 return buf.ToString();
167 }
168
169 protected override string GetConstructorDeclaration(MethodDefinition constructor)
170 {
171 var buf = new StringBuilder();
172
173 var typeName = GetName(constructor.DeclaringType);
174 buf.Append("var ");
175 buf.Append(CamelCase(typeName));
176 buf.Append(" = new ");
177 buf.Append(typeName);
178 buf.Append("(");
179 AppendParameters(buf, constructor, constructor.Parameters);
180 buf.Append(");");
181
182 return buf.ToString();
183 }
184
185 private bool IsAsync(MethodDefinition method)
186 {
187 return method.CustomAttributes.Any(i => i.AttributeType.FullName == "System.Runtime.CompilerServices.AsyncStateMachineAttribute");
188 }
189
190 protected override StringBuilder AppendNamespace(StringBuilder buf, TypeReference type)
191 {
192 return buf;
193 }
194
195 protected override string GetEventDeclaration(EventDefinition e)
196 {
197 // Usage:
198 //function on[EventName](eventArgs){/* Your code */}
199 //[class name, camel cased].addEventListener(“[event name, all lower-case]”, on[EventName]);
200 //[class name, camel cased].removeEventListener(“[event name, all lower-case]”, on[EventName]);
201 // If the event supports property syntax (it has a corresponding EventName property), add this:
202 // - or -
203 //[class name, camel cased].on[event name, all lower-case] = on[EventName];
204 if (!e.AddMethod.IsPublic)
205 return null;
206
207 var className = e.AddMethod.IsStatic ? ProcessFullName(e.DeclaringType.FullName) : CamelCase(GetName(e.DeclaringType));
208 var eventName = e.Name;
209 var eventNameLowerCased = eventName.ToLower();
210 var buf = new StringBuilder();
211 buf.Append("function on");
212 buf.Append(e.Name);
213 buf.Append("(");
214 buf.Append("eventArgs");
215 buf.Append(") { /* Your code */ }");
216
217 buf.Append(GetLineEnding());
218 buf.Append(className);
219 buf.Append(".addEventListener(\"");
220 buf.Append(eventNameLowerCased);
221 buf.Append("\", on");
222 buf.Append(eventName);
223 buf.Append(");");
224
225 buf.Append(GetLineEnding());
226 buf.Append(className);
227 buf.Append(".removeEventListener(\"");
228 buf.Append(eventNameLowerCased);
229 buf.Append("\", on");
230 buf.Append(eventName);
231 buf.Append(");");
232
233 buf.Append(GetLineEnding());
234 buf.Append("- or -");
235 buf.Append(GetLineEnding());
236 buf.Append(className);
237 buf.Append(".on");
238 buf.Append(eventNameLowerCased);
239 buf.Append(" = on");
240 buf.Append(eventName);
241 buf.Append(";");
242
243 return buf.ToString();
244 }
245 }
246 }