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.
Related
Since Objective-C I'm a fan of #pragma MARK: but recently I've seen /// -Tag: in Apple's source code. Also noteworthy, it's highlighted in white, while MARK isn't. Tag on the other side does not add any text to the Xcode 'outline' view.
Can anyone explain what the purpose of Tag is?
The - Tag: annotation is used to locate specific places of your own code. You can include it as part of symbols documentation in Swift. E.g. you may add a Tag marker in some Swift file next to a function:
/// - Tag: myFunction
func myFunction() {
print("My function is called")
}
In another file you can refer to this exact place in the code as part of another Swift entity documentation:
/// Uses [myFunction](x-source-tag://myFunction) internally
func anotherFunction() {
myFunction()
}
When using the Quick Help popover on anotherFunction in Xcode, you get an interactive reference (under myFunction text), which takes you to the file (and line) where the /// - Tag: myFunction is located:
I haven't been able to find anything specific to the Tag documentation keyword. It appears to be a custom documentation keyword, though it doesn't appear in Quick Help as expected...
I'm guessing that it may just be a way to allow searching for related code... Maybe it'll come up as a new feature in the future - used to apply "tags" to specific symbols, as you would in Finder, say. That seems reasonable, given that the function referenced in the question is related to custom clustering (see Decluttering a Map with MapKit Annotation Clustering), and the documentation line says /// - Tag: CustomCluster.
When you write a function, you can document the details of that function in Swift using a version of "markdown". See the Markup Formatting Reference and CommonMark for examples.
This documentation appears in the Quick Help popover box, as shown in the question, and in the Quick Help Inspector - displayed in the right-hand panel when your cursor is in a symbol (function name, for example), and you click the question mark in a circle at the top of the inspector panel.
Many pre-defined keywords exist for this documentation, such as - Parameters:, - Returns:, and - Throws:. And, you can also use your own custom keywords. Usually the custom keywords appear in the Quick Help as well, but this - Tag: keyword doesn't seem to do anything (at least in Xcode 9.4.1).
Here's an example of how to use Swift Documentation Markup:
/// Errors associated with String processing.
enum StringError: Error {
case cantCapitalizeAnEmptyString
}
/// Capitalizes a String item.
/// - Tag: I don't know what this is - it doesn't show in Quick Help.
/// - Parameter string: A String item to be capitalized.
/// - Throws `StringError.cantCapitalizeEmptyString` when provided String item is empty.
/// - Returns: The provided String item converted to all capital letters.
/// - Blah: A custom keyword I made up.
func capitalize(string: String) throws -> String {
if string.isEmpty {
throw StringError.cantCapitalizeAnEmptyString
}
return string.capitalized
}
Then, in the Quick Help Inspector, you'll see:
Or, of course, option-clicking the function name will display the Quick Help popover:
As noted in the question, the - Tag: keyword doesn't display anything in either the Quick Help Inspector or the Quick Help popover.
I have a rather large Dart application that uses part and part of so that I don't have to use relative imports. However, the application may have something like this at the entry point file:
part 'file1.dart';
part 'file2.dart';
part 'file3.dart';
part 'some_sub_dir/file1.dart';
part 'some_sub_dir/file2.dart';
part 'some_sub_dir/file3.dart';
part 'some_sub_dir/file4.dart';
part 'some_sub_dir/file5.dart';
part 'some_sub_dir/file6.dart';
...
As far as I know, my IDE (WebStorm) doesn't automatically add a part statement when I create a new class. Is there any way I can avoid having to use so many parts? If not, can the process of adding new parts each time be automated?
I understand your problem as I can and I'll try to answer from my experience in Dart.
As I got it you are trying to keep all (or a lot) project files as parts of one library. It's wrong conception. In Dart library is not big thing. Here is few advices how to organize your files.
Don't try to keep a lot of files as parts of one library. Rather keep each file as separated library.
You can keep few classes in one file. But be sure classes works together for one idea.
You can split one library in few part files only if it has a lot of classes or one class is too big. But be sure all this files should be together in one library.
If you don't know how to combine classes in libraries keep each class in separated library. After days you will get understanding which classes plays together.
If one class from one library has usages in not only library but in other libraries - make it separated library.
Place parts in same folder with main library file.
If library has parts put all library files into separated folder.
Use relative links to parts.
Always use absolute links to other libraries. It will help you to make refactoring in future.
For example, this is a project like TODO list application. So, we have view class:
// This is a view html component class. //
library todolist.list_viewer;
import 'package:todolist/task.dart'; // model class
class ListViewer extends HtmlElement {
// it showes list of tasks
}
class TodoRenderer extends HtmlElement {
// this is a renderer for one todo item
}
And this is a model class:
// This is a todo model task //
library todolist.task;
class TodoProvider {
List<TodoItem> todos;
String addItem(TodoItem new Todo) {
//...
}
}
class TodoItem {
String Author;
DateTime date;
}
It looks simple now, divided into separated libraries. But if we want to add RecId class to keep todo database id it becomes too complex. We should split it in two libraries: todo_provider and todo_model and put RecId class into last one. Now it's good again.
If we wanna add one more model: a User, so each todo item may have executor or author. We can't just put it todo_model. Now we should to combine TodoItem and User classes into model library. So we just rename todo_model class to model and add User class into it.
Or instead last action we can make user_model library to keep User class. And as User model has recId property too we should extract RecId class into separated library.
It's all depends on how our classes big and complex.
I understand that:
part/part of is used to break a library into several parts (scripts). You have visibility to public and private members.
import is to "call/use" another library from your library. You have only visibility to public members of the imported library.
WebStorm can't infer you want a script to be part of your library.
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"/>
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.
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.