I am playing with code documentation and live templates and I quite don't get it.
I've read Dr.Bob's article about generating documentation and wiki articles about live templates but I have one problem with class description.
By class description I understand the IDE behaviour when I point my mouse cursor over class declaration.
For example, I have such class with it's description:
type
{$REGION 'TMyClass'}
/// <summary>
/// Summary works
/// </summary>
/// <remarks>
/// Remarks works
/// </remarks>
/// <exception cref="www.some.link">This works</exception>
/// <list type="bullet">
/// <item>
/// <description>description does not work</description>
/// </item>
/// <item>
/// <description>description does not work</description>
/// </item>
/// </list>
/// <permission cref="www.some.link">This works</permission>
/// <example>
/// <code>
/// Code example does not work
/// </code>
/// </example>
{$ENDREGION}
TMyClass = class
private
a, b, c: Integer;
public
end;
And later in the code I have such declaration:
var
MyObject: TMyClass;
When I put mouse cursor over the class type I have such description:
As you see not every html tag was rendered by the IDE engine. I would really want to know how to render additional tags, especially tag with code example. Is it possible?
I am using Delphi 2009 Proffesional.
Only limited set of tags is supported. The best documentation about this stuff I'm aware of is the DevJET Software's Delphi Documentation Guidelines (at the end of the "Table of Contents" there is link to the PDF).
The tags Help Insight supports are described in the online help and the Delphi docwiki. They are a subset of the tags C#'s help tags support. No other tags than the ones listed on the Embarcadero site seem to be supported (I have tried them). The only other things that work (and are required) are "<", ">" and """.
Update
There seem to be some products that allow you to use the full syntax as e.g. described in the Delphi Documentation Guidelines linked to by #ain. But that requires you to buy a commercial product like DevJet's Documentation Insight, which should not be confused with the Help Insight the IDE supports since Delphi 2006.
As you found out, and I did too, only the subset described in the Delphi docwiki is supported by the bare IDE without commercial products. There is also the documentation that is supported by the Modelling interface, but that is different again. In the normal IDE, you can only use the tags you and I already found.
Related
I am an amator astronomer and I write driver for telescope with Delphi and the standard ASCOM
First a special thank to David Heffernan who has helped me a lot these 2 last months. I have made a lot of progress in the writing of drivers, and there is a judge: 'Conform', a program which test all the compatibilties of a driver. At the beginning it was very bad, and now I am on the good way. The last really unsolved problem is an ArrayList of string.
The documentation of Ascom Telescope driver has a property:
C#
ArrayList SupportedActions { get; }
Visual Basic:
ReadOnly Property SupportedActions As ArrayList
Get
Visual C++
property ArrayList^ SupportedActions {
ArrayList^ get ();
}
Field Value
An ArrayList of strings (SafeArray collection) containing the names of supported actions.An array list collection has been selected as the vehicle for action names in order to make it easier for clients to determine whether a particular action is supported. This is easily done through the Contains method. Since the collection is also ennumerable it is easy to use constructs such as For Each ... to operate on members without having to be concerned about hom many members are in the collection.
Collections have been used in the Telescope specification for a number of years and are known to be compatible with COM. Within .NET the ArrayList is the correct implementation to use as the .NET Generic methods are not compatible with COM.
So I have tried to make an automation object:
And the big judge "Conform" program send me that (sorry it's a translation of an error message in french):
ERROR .NET - Exception: System.InvalidCastException: Impossible to make a cast of a COM object of type 'System.__ComObject' in type of class 'System.Collections.ArrayList'. The instances of type representing COM component, can't be casted in types different from representing COM components; however they can be casted in interfaces until the COM component underlying takes in charge the calls QueryInterfacefor the IID of the interface!!!!!!!!!!!!!!!!??????????????
Chinese or old Greek are more obvious for me.
The only thing I have found is that in regedit:
Thanks again for your help.
For your eyes only, a picture made with my telescope and some home-writed program:
The solution was so simple!!! I found it on a web page. You want an ArrayList from .net?? Make it:
function TTelescope.Get_SupportedActions: OleVariant;
var
capacity: Integer;
item:Variant;
dotNetArrayList:Variant;
begin
{ Create object }
dotNetArrayList := CreateOleObject('System.Collections.ArrayList');
{ Add an element }
dotNetArrayList.Add('Un élément chaîne');
item := dotNetArrayList.Item(0);
Result:=dotNetArrayList;
end;
And it's working perfectly. Nevertheless, thanks a lot for your answers, and perhaps a day I will try to learn C#.
When using XML Documentation Comments, I can't figure out how I can refer to another class member. Take this code:
TGreeter = class
/// <summary>Says hello</summary>
procedure Hello;
/// <summary>Says hello to all</summary>
/// <remarks>
/// This is the same as <see cref="Hello"/>, but it says hello to all
/// instead.
/// </remarks>
procedure HelloAll;
end;
Help Insight displays the help for HelloAll fine, but if I click on the link to Hello it does nothing (almost nothing; the mouse pointer indicates that, for a second or so, it does some thinking, but then it stops). What is the correct way to make such a cross-reference?
I was wondering myself for quite a long time before I found a syntax that works (tested with Delphi XE4): You need to put the unit name, a pipe, the class name, a point and then method name.
In your example, let's say that the unit is called "MyUnit", then you should use:
<see cref="MyUnit|TGreeter.Hello"/>
Seems a simple task but despite google and looking at all the menus I cannot find how to look at documentation of classes or objects in XNA.
In unity you just press ctrl and ' what is is in visual c#/XNA? I am looking for information on created classes/Objects not the online documentation/Help.
You can search the MSDN for the required information. For example, here is a link for the SpriteBatch class.
The MSDN is not just limited to XNA, it is a useful tool for all Microsoft based languages.
Please note that some of the XNA documentation is not very informative. I've come across pages on XNA functionality that contain only one or two lines - no example code either!
What about classes that people have created and documented?
The author of the code will need to provide documentation in the code. Here is an example:
/// <summary>
/// This is an example of XML documentation for a class.
/// </summary>
class Program
{
/// <summary>
/// This is an example of XML documentation for a public method.
/// </summary>
/// <param name="name">The name we are validating.</param>
/// <returns>True if valid, otherwise false.</returns>
public bool IsValid(string name)
{
return true;
}
}
Visual Studio will automatically generate most of the XML for you. Just type "///" above the class/method to begin. You can read more on it here.
You will now be able to view the code documentation by hovering over the class/function name.
To anyone who might get this problem in the future - I have solved it.
The files are .chm files and are located in the folder of the classes when available.
Another issue when you are downloading them from another computer to be aware of is they are sometimes blocked.
If that is the case - right click them/properties/general and in the lower right corner there is a button (Unblock) click this, reload the .chm file and all should be readable.
So glad I found this I was starting to question my sanity and it appeared no one else was aware of them or at least understood my problem.
This question already has answers here:
Closed 10 years ago.
Possible Duplicate:
Code documentation for delphi similar to javadoc or c# xml doc
I have been utilizing the Documentation capabilities of RAD Studio Delphi XE2 across most of my global source (libraries such as business rules, components/controls, etc.). This places some commented text just before the declaration of various things in your source code, like so:
type
/// <summary>
/// This class is used for this and that.
/// </summary>
TMyObject = class(TObject)
....
or even
/// <summary>
/// This function does this and that.
/// </summary>
/// <returns>
/// This is the result of what DoSomething produces.
/// </returns>
/// <remarks>
/// DoSomething is only a sample function for demonstration purposes.
/// </remarks>
function DoSomething: String;
The main reason I've been doing this is so that when you hover over a symbol, when it shows the insight, it will include this documentation text with it. For example, in a completely separate unit, hover over the text DoSomething wherever it's used and it will show you a hint box containing the exact text written in this documentation.
Hint: press either Ctrl+Shift+D or Ctrl+Alt+D (I've seen both those on different PC's) and it will open a window to make things easier. I stumbled across this when pressing Ctrl+Shift+S to save but accidentally hit D.
What I would like to know is how can I export this documentation to a CHM help file? I would like to make a help file linked to my library so a developer can use F1 in the code and see an explanation of what the code does. Just like the standard Delphi source documentation (and most other languages).
It's not a CHM file but if you use Delphi Enterprise or higher the IDE has the ability to produce documentation using your properly formatted source code comments.
Please could someone explain me what's the difference between public and published class members in Delphi?
I tried to look at Delphi help and I understand that these members have the same visibility, but I don't understand very well how they differ and when should I use published members instead of public ones.
Thanks a lot.
The compiler generates RTTI (Run-Time Type Information) metadata for published members, but not for public members (by default). The main effect of this is that the published properties of an object will appear in the Object Inspector at design time.
I do not know if you are writing components, but if you do, you probably know that properties and events are normally published, so that they can be set using the Object Inspector.
Public
public
property MyProperty: integer read FMyProperty write FMyProperty
MyProperty will not be visible in the Object Inspector.
Published
published
property MyProperty: integer read FMyProperty write FMyProperty
MyProperty will be visible in the Object Inspector.
Public properties and published properties have the same visibility, as you already stated. Published properties are included in RTTI, public properties aren't.
As a side note, there is another special thing with published:
The default visibility of class members is published, so check for unsafe code like:
TTopSecret = class(TObject)
Name: string;
Password: string;
function DecryptPassword(const AValue): string;
public
constructor Create(const AName, AEncryptedPassword: string);
end;
Name, Password and DecryptPassword() are visible 'world-wide'.
Published properties will export Runtime Type Information (RTTI).
Have a look here about RTTI in Delphi
It seems there are lots of good answers already, pointing out the Object INspector, RTTI,
etc. These are all pieces of the puzzle.
If you take away the published keyword, the entire Delphi RAD tool design would require some way to specify which properties are stored in a DFM, inspected in the component property inspector, and can be reloaded at runtime from a DFM when the form or data module is created.
This, in a word, is what Published is for. It is interesting to me that the designers of QT (originally TrollTech, later part of Nokia, later still spun off to Digia) had to emulate this level of RTTI for their C++ RAD library "QT", adding a "published" equivalent and a "property" equivalent, while pure C++ still lacks this fundamental facility.
Runtime Type Informations (RTTI) are only generated for published class members.
At run-time, entries in the published and public sections are equally accessible.
The principal difference between them is that published items of a component appear in the Object Inspector at design-time.
This happens because, for fields in published section RTTI is automatically generated.
The Object Inspector picks this up and uses it to identify what to add to its list of properties and events.
In addition to the other answers:
Published properties are automatically stored by the streaming system.
For instance if you have a TComponent's descendant instance and write it to a TStream with WriteComponent, all (well, not all, but that is another question) published properties are written to the stream without any further coding.
Of course, the streaming system only can do that because the RTTI is available for those published properties.