I'm looking over the documentation on doc comments in Dart, and came across the following:
/// Links can be:
///
/// * https://www.just-a-bare-url.com
/// * [with the URL inline](https://google.com)
/// * [or separated out][ref link]
///
/// [ref link]: https://google.com
///
But I've noticed a couple of things when I'm trying this in IntelliJ:
I can't get the link to show as a hyperlink (when pressing ctrl + q to open documentation) when part of a list item (by starting the line with any of these 1. * - +)
I can't get the 1st or 3rd forms of link expression to work, even outside of a list.
I'm trying to add a doc comment to a method that uses a dependency, and link to the dependency in the comment. Here's the comment that I have:
/// Doing dot product with a layer of neurons and multiple inputs
///
/// Associated YT NNFS tutorial: [Part-3](*youtube link here*)
///
/// This uses the [ml_linalg][1] dependency. You can also use the [linalg][2] dependency
///
/// [1]: https://pub.dev/packages/ml_linalg
///
/// [2]: https://pub.dev/packages/linalg
Here's a screenshot of how IntelliJ renders the documentation. The youtube link shows fine (using the second approach from the documentation) but clutters up the doc comment for the writers/editors of the docs. But as you can see, the third form doesn't work at all. The text in the square brackets isn't turned into a link and the text in second set of square brackets is just concatenated onto the text of the first.
If anyone knows how I can add links to my doc comments as part of a list, as well as put a marker to the link and have the full URL at the end of the doc comment as in the 3rd example given, that would be greatly appreciated. Thanks so much in advance
Related
I use NSwag in an ASP.Net WebAPI project to generate a swagger interface - which works great.
Say I have a method I want to add some explanations to - how can I do that?
By comment I mean something that when a user of the API is looking at the documentation will see.
I have googled, binged and ... ducked? - but was unable to find anything about it. Maybe I am using wrong terms.
To use annotation-based documentation with NSwag you must install the package NSwag.Annotations.
Then you can use annotations like that:
[SwaggerResponse(HttpStatusCode.OK, typeof(MyResponseType), Description = "Returns the object containing data ...")]
You can use Document comments to achieve your goal. For example
/// <summary>This method changes the point's location by
/// the given x- and y-offsets.
/// <example>For example:
/// <code>
/// Point p = new Point(3,5);
/// p.Translate(-1,3);
/// </code>
/// results in <c>p</c>'s having the value (2,8).
/// </example>
/// </summary>
public void Translate(int xor, int yor) {
X += xor;
Y += yor;
}
Translate is your API method and you've added proper documentation comments NSwag will pick those up and show them when you explore the API via the API explorer. If that doesn't work add the following in your .csproj
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
Alternatively to the XML approach posted in another answer you can use the Swashbuckle.AspNetCore.Annotations package as well if you prefer an attribute-based approach.
I'm struggling to get all the required (and only the required) information into the documentation of my Enterprise Architect Project. Precisely: we have modelled various requirements and displayed the source "standards" for these requirements in our diagrams by using the "hyperlink"-element out of the common toolbox. (This allows us to capture a title, the website where the documentation is found and a description of this documentation).
Now this element is visible on the diagram, but not in the package-view of our model and it does not get generated in our word (docx) documentation.
I can see that it should be possible to get this in the documentation, because a "Model Report" which basically prints everything does print the hyperlinks. But I can't find what I have to select in my template (in the package-tree view, as a package field, element field or diagram field) in order to get this printed. I can't just use the model report since this basically dumps the whole database in the document and reverse-engineering this model report has proven too difficult for me. Actually I would expect this to be in some kind of documentation for EA, but could not find such a thing with this level of detail... is there, is there a reproducible way of finding such things out in further cases? (btw I'm using EA 11.0)
[sorry there were illustrations here, but I'm not allowed to upload them...]
As Geert has already noted, there is a difference between "proper" elements and diagram-only elements. This is actually reflected in the document template editor, where there is an "Element" section inside the "Diagram" section. This will produce output for all elements in the diagram, whether or not they are also in the project browser.
Here's an example of the information you can pull out of your hyperlinks. Given a diagram with a hyperlink:
... and a template which outputs name, alias and hyperlink for each element in the diagram:
... EA will generate a document will the following contents:
So if you want the hyperlink to result in a hyperlink in the document, use the HyperlinkAlias field.
What might be a bit confusing is the fact that in addition to the Hyperlink element type in the Common diagram toolbox, EA allows you to create hyperlinks in regular elements (in the Element Properties dialog, Related tab: Files, which can be local files or web addresses).
In fact, I would recommend that you use those in your Requirement elements rather than diagram-only Hyperlinks if traceability is a priority in your model. The diagram-only Hyperlinks, on the other hand, give you a clearer visual.
Selecting a subset of the elements in a diagram ("only the required information") is a little more involved and depends on how your model is structured. Template fragments will get the job done, but you might be able to achieve your desired result by just using the filters in the document generation dialog.
The hyperlink is an element that is stored in the same package as the diagram it is used on, it is just not visible in the project browser (similar to a note element).
There's a good chance that it doesn't have a name, so make sure you don't omit nameless elements.
So if you print all the element of the package containing the diagram then you should be able to print the hyperlink as well.
In case that fails you might want to consider creating a template fragment based on an SQL query or a script. Those offer lots of flexibility to print whatever you need, even if it is located in a different package.
[Edited on 04.05.15 to reflect the comment by Uffe and provide a final solution]
Ok, based on Geerts answer, using the following custom query fragment in the diagram section:
select
t_object.ea_guid as CLASSGUID,
t_object.Object_Type as CLASSTYPE,
t_object.Object_Id as OBJECTID,
t_object.name as HL_Name,
t_object.Stereotype as HL_Stereotype,
t_object.object_type as HL_Type,
t_object.Alias as HL_Alias,
Note as Notes
--,t_object.*
from t_object
left join t_diagramobjects on (t_object.Object_ID = t_diagramobjects.Object_ID)
left join t_diagram on (t_diagram.Diagram_ID = t_diagramobjects.Diagram_ID)
where t_diagram.Diagram_ID = '#DIAGRAMID#'
and t_object.Object_Type='Text'
I was able to get a list of the hyperlinks following the diagram, this is the fragment:
custom >
{HL_Alias}: {HL_Name}
{Notes}
< custom
The "Notes" can be printed by getting the attribute directly out of the t_object table. Don't get confused as I was at first: the auto-completion on t_object and the results (t_object.*) DO NOT SHOW a Note-Attribute, but it does exist an when you write it into the query, it gets generated in the document.
Does anyone know how? I'm trying to make a method that the intellisense shows another name instead of the name you ta the method. example:
The code looks like this:
Public Shared Sub Anything(ByVal blablabla....)
(...)
End Sub
And I want to auto-complete the VisualStudio menu be like:
Async
Alalala
Anymethod
Anything - Like these
Basic
On mouse hover:
instead of...
Public Shared Sub Namespace.Anything(ByVal blablablbal....)
This is the summary...
put it:
Anything <expression>
This is the summary...
-or-
Sub Anything
This is the summary...
Any ideas? thx...
I believe you're talking about XML Comments. Without comments:
With comments:
And Intellisense then also displays the parameter information as you get to each parameter:
Sooooo, I hope my answer isn't too vague. I'd love to help you igure it out either way.
Basically - you have to override the XML Documentation that Intellisense uses, in order to MAP a new MethodName to a Differently-Named method within your assembly.
Intellisense uses an XML Skeleton to define the different properties of what you see. That Skeleton typically looks something like this:
<CodeElement type="Function">
<Template>
<summary/>
<param/>
<returns/>
<remarks/>
</Template>
<CompletionList>
<exception cref=""/>
<include file="" path=""/>
<param name=""/>
<remarks/>
<returns/>
<summary/>
</CompletionList>
</CodeElement>
You can use this template to generate the Intellisense data you're looking for. In real-life application, this would look something like this:
''' <summary>
'''
''' </summary>
''' <param name="str"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function Anything(ByVal str As String) As String
Try
...
Now, this template is Editable
The Visual Basic compiler generates an XML document for your assembly with all the XML comments defined in the code. The compiler will also resolve symbols used in cref, permission, and name attributes, as well as file references in include elements.
The generated file doesn't show your commented members hierarchically. Rather, it is a flat list. It includes a unique ID string for each definition that allows the comments to be mapped back to their definitions in code (see Code Snippet below).
In this case, the string is M:Namespace.Anything(System.String). M stands for method, Namespace specifies the path, System.String the parameter type.
THIS is where you would override the NAME of the Method that INTELLISENSE sees, without effecting the actual Method itself.
<?xml version="1.0" ?>
<doc>
<assembly>
<name>AnyLib</name>
</assembly>
<members>
...
<member name="M:Namespace.Anything(System.String)">
<summary>Does something</summary>
<param name="str">str to pass into method</param>
<returns>A string</returns>
</member>
...
</members>
</doc>
You can generate the XML documentation file using either the command-line compiler or through the Visual Studio interface. If you are compiling with the command-line compiler, use options /doc or /doc+. That will generate an XML file by the same name and in the same path as the assembly. To specify a different file name, use /doc:file.
If you are using the Visual Studio interface, there's a setting that controls whether the XML documentation file is generated. To set it, double-click My Project in Solution Explorer to open the Project Designer. Navigate to the Compile tab. Find "Generate XML documentation file" at the bottom of the window, and make sure it is checked. By default this setting is on. It generates an XML file using the same name and path as the assembly
In short - yes, it is possible, but very cumbersome and makes re-using your code very difficult. Check this link for a more detailed overview:
https://msdn.microsoft.com/en-us/magazine/dd722812.aspx
I've found that searches that contain 'of', 'and', 'the', etc. will not return results because Lucene has removed stop words. So if I search for a item that had a title of "Aftermath of the first world war" I will get zero results.
But if I strip 'of' and 'the', then I am searching for "aftermath first world war". I will get the expected document back.
Does the ContentSearch API remove stop words from queries? Is this something one can configure Lucene to remove? Or should I remove these stop words before building my query?
Thanks
Adam
You can configure Sitecore Standard Analyzer to accept your own custom set of Stopwords.
Create an text file with the stopwords (one stop word per line) and then Make the below config changes in the Sitecore.ContentSearch.Lucene.DefaultIndexConfiguration.config file
<param desc="defaultAnalyzer" type="Sitecore.ContentSearch.LuceneProvider.Analyzers.DefaultPerFieldAnalyzer, Sitecore.ContentSearch.LuceneProvider">
<param desc="defaultAnalyzer" type="Lucene.Net.Analysis.Standard.StandardAnalyzer, Lucene.Net">
<param hint="version">Lucene_30</param>
<param desc="stopWords" type="System.IO.FileInfo, mscorlib">
<param hint="fileName">[FULL_PATH_TO_SITECORE_ROOT_FOLDER]\Data\indexes\stopwords.txt</param>
</param>
</param>
</param>
Further Reading : I have written an blog post about this issue and might be of help http://blog.horizontalintegration.com/2014/03/19/sitecore-standard-analyzer-managing-you-own-stop-words-filter/
I think this is the same problem with problem from this blog.
Can you try to follow the steps from the blog post?
Other option can be to create a custom analyzer and to give to the constructor your stopWords list.
Something like:
public class CustomAnalyzer : Lucene.Net.Analysis.Standard.StandardAnalyzer
{
private static Hashtable stopWords = new Hashtable()
{
{"of", "of"},
{"stopword2", "stopword2"}
};
public CustomAnalyzer() : base(Lucene.Net.Util.Version.LUCENE_30, stopWords)
{
}
}
After you modify you need to change your config file. A nice blog post about Analyzer you can find here.
P.S.: I didn't try my code if is really working.
I have to generate a PDF of a Quote Order on Approval. So, I'll have to do it via a Trigger.
But, I can't access a VF Page from Trigger since I'm formatting the content using the VF Page and renderas="PDF" in Page.
So, I tried to use a future class to do the same. But, there comes another issue regarding the usage of pagereference.getContent() or pagereference.getContentAsPDF() methods : these methods are not supposed to be used in a future class.
So, can anyone suggest me some idea to generate a pdf and attach it to quote.
For me this seems to be the easiest way to address that.
call into the trigger your XXPDFGenerator class adding the need record
create a class XXPDFGenerator
add generatePDF and attachPDF methods
generate the html into generatePDF method
convert to PDF and insert the attach as this sample
Attachment attachmentPDF = new Attachment();
attachmentPDF.parentId = record.Id;
attachmentPDF.Name = record.Name + '.pdf';
attachmentPDF.body = Blob.toPDF(pdfContent); //This creates the PDF content
insert attachmentPDF;
Complete info on Cory Cowgill blog