Creating XML Documentation

This forum is meant for questions and discussions about the X# language and tools
Post Reply
leon-ts
Posts: 429
Joined: Fri Feb 03, 2017 1:43 pm

Creating XML Documentation

Post by leon-ts »

Hi devteam,

When compiling a XSharp project, a documentation file (XML) is always created with the project name in the solution, instead of using the name of the file from the project properties (section <DocumentationFile> SomeFile.Xml </DocumentationFile>).

For example,
the project is called "001 - MyCompany.MyProject"
output file name: MyCompany.MyProject.dll
in the project properties, the documentation file is set as "MyCompany.MyProject.xml"

after Build, the file "001 - MyCompany.MyProject.xml" is created on the disk instead of the file "MyCompany.MyProject.xml"

Is it so intentional or is it a bug?

Best regards,
Leonid
Best regards,
Leonid
leon-ts
Posts: 429
Joined: Fri Feb 03, 2017 1:43 pm

Creating XML Documentation

Post by leon-ts »

Addition:

When displaying the description of functions from the documentation, only the first parameter is visible. If there is a second, third, etc., then they will not appear in the tooltip.

Code: Select all

<param name="param1">description1</param>
Also, the documentation for the return value is not displayed.

Code: Select all

<returns>description</returns>
The same problem when displaying documentation for XSharp functions (for example, from the XSharp.Core.xml file).
See XSharp.CoreDb.Eval() for an example.
Best regards,
Leonid
User avatar
robert
Posts: 4266
Joined: Fri Aug 21, 2015 10:57 am
Location: Netherlands

Creating XML Documentation

Post by robert »

Leonid,
The description for the second parameter appears when you press the comma.
This works the same as the C# integration in VS.
I don't see the the documentation for the return value in C# as well.
Where/When should that be displayed ?

Robert
XSharp Development Team
The Netherlands
robert@xsharp.eu
User avatar
robert
Posts: 4266
Joined: Fri Aug 21, 2015 10:57 am
Location: Netherlands

Creating XML Documentation

Post by robert »

Leonid,
after Build, the file "001 - MyCompany.MyProject.xml" is created on the disk instead of the file "MyCompany.MyProject.xml"
This looks like a bug in the VS integration.
I'll look into this.

Robert
XSharp Development Team
The Netherlands
robert@xsharp.eu
leon-ts
Posts: 429
Joined: Fri Feb 03, 2017 1:43 pm

Creating XML Documentation

Post by leon-ts »

Robert,
robert wrote: The description for the second parameter appears when you press the comma.
This works the same as the C# integration in VS.
Robert, thanks! I didn’t know that.

Regarding the <returns> tag:
https://docs.microsoft.com/en-us/dotnet ... oc/returns

The description of the returned value is displayed in the "Object Browser" window (menu "View -> Object Browser"). But it seems that XSharp does not show detailed information about objects in this window, as C# does.

Best regards,
Leonid
Best regards,
Leonid
User avatar
robert
Posts: 4266
Joined: Fri Aug 21, 2015 10:57 am
Location: Netherlands

Creating XML Documentation

Post by robert »

Leonid,
The object browser can show information for code from external assemblies as well as for code that is defined in source code.
For the code from external assemblies (such as a reference to XSharp.Core) you should see the same information as you can see in the helpfile. I can see the various parameters and return type for XSharp.CoreDb.Eval() for example.
For types and methods defined in the source code, we are not showing the documentation comments there yet.
This is on our todo list, but not very high I am afraid.

Robert
XSharp Development Team
The Netherlands
robert@xsharp.eu
leon-ts
Posts: 429
Joined: Fri Feb 03, 2017 1:43 pm

Creating XML Documentation

Post by leon-ts »

Robert,
robert wrote:For the code from external assemblies (such as a reference to XSharp.Core) you should see the same information as you can see in the helpfile.
It really works. Thanks!

Best regards,
Leonid
Best regards,
Leonid
leon-ts
Posts: 429
Joined: Fri Feb 03, 2017 1:43 pm

Creating XML Documentation

Post by leon-ts »

Robert,

Is it possible to implement the display of default values for parameters, as implemented in VO or C#?
For example, there is a method:

Code: Select all

METHOD MyMethod(a AS INT, b := 5 AS INT, c := 10 AS INT) AS INT
When working with this method in code, Intellisense displays as a hint only:
EXPORT METHOD MyMethod(a AS INT, b AS INT, c AS INT) AS INT
and hides the default values for b and c.

It can be very difficult to write code without knowing the default values for the called method.

Best regards,
Leonid
Best regards,
Leonid
User avatar
robert
Posts: 4266
Joined: Fri Aug 21, 2015 10:57 am
Location: Netherlands

Creating XML Documentation

Post by robert »

Leonid,
I will see what I can do.
We'll be touching the project system and intellisense this month anyway, so we can include this.
Can you create a Github issue, so we won't forget?

Robert
XSharp Development Team
The Netherlands
robert@xsharp.eu
leon-ts
Posts: 429
Joined: Fri Feb 03, 2017 1:43 pm

Creating XML Documentation

Post by leon-ts »

Best regards,
Leonid
Post Reply