I am trying to use the <code> tag inside the <example> tag to show a sample code in xml documentation. However, when I build the Sandcastle project, I see that it is shown as C#. There is no language attribute in <code> tag. And I could not find a setting in Sandcastle's project properties. Am I missing something?
BTW, I am using HtmlHelp1 format.
Actually, if you move beyond Sandcastle to Sandcastle Help File Builder (SHFB),
you will get both an easier to use interface to Sandcastle and additional features for your documentation set, including just what you want: a language attribute (language) for the <code> element.
Note that SHFB generates a language selector menu but that only lets you
show or hide a particular set of languages (C#, VB.NET, C++, J#, JScript.NET, XAML, and JavaScript). It supports colorizing, though, of a larger set (C#, VB.NET, JScript.NET, C++, J#, C, JavaScript, VBScript, XAML, XML, HTML, SQL script, PowerShell script, and Python). (From the Code Block Component section of the SHFB documentation.)
I have written extensively on this point, as well as many other tips and pitfalls of Sandcastle and SHFB, in my article Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code published on Simple-Talk.com. Besides the main article, I also put together a wallchart/quick reference that gives you everything you need to know to use Sandcastle/SHFB on one page--the link also appears at the end of the article.
You can find more details about the <code> element in the Displaying Sample Code section of my article, as well as from the official SHFB documentation at Importing and Colorizing Code from Source Files.
Related
So I want to create my own programming language in vb.net 2013 and I see SyntaxEditor by actipro software fits, but how do I write xml definition file that tells which words how to be colored? is there a tutorial somewhere?
Also, how do I make the syntax editor to display the number of the line?
SCREENSHOOT OF MY PROGRAM
Showing the line number is just a property of the SyntaxEditor-control: in WPF-version it is "IsLineNumberMarginVisible". you have to set it to "true". I assume the property in WinForms-version has the same name.
when you install Actipro then there are a lot of samples included. Just look for files named *.langdef and you will find a lot of files where you can see how they shall look like.
There is also a tool "LanguageDesigner.exe" delivered with SyntaxEditor. It gives you a nice UI to create and edit the language file.
Generally I recommend to take a look at the sample projects, specially the SampleBrowser-Project with the "GettingStarted01" to "GettingStarted15" controls.
I have a custom XML format that links to Java resources. For the sake of simplicity let's assume my XML file would look like this:
<root>
<java-class>my.fully.qualified.class.name</java-class>
</root>
Eventually my references will be somewhat more complicated. It will not contain the fully qualified class name directly and I will need some logic to resolve the correct class, but I want to keep the example as simple as possible here.
Now I want it to be possible to Strg+Click on the element's text and want IntelliJ to carry me to the .java file, just like it is possible in Spring-XML files. In the IDEA Plugin Development FAQ there is a link called "How do I add custom references to Java elements in XML files?" which so much sounds like exactly what I need. Unfortunately it links to a discussion where someone is more or less done implementing something like this, having some minor problems. Nevertheless I understood that I probably need to write an implementation of the interface com.intellij.psi.PsiReference. Googling for "PsiReference" and "IntelliJ" or "IDEA" unfortunately did not bring up any tutorials on how to use it, but I found the class XmlValueReference which sounds useful. Yet again googling for "XmlValueReference" did not turn up anything useful on how to use the class. At least the PSI Cookbook tells me that I can find the Java class by using JavaPsiFacade.findClass(). I'd be thankful for any tutorials, hints and the like, that tell the correct usage.
The above linked discussion mentions that I need to call registry.registerReferenceProvider(XmlTag.class, provider) in order to register my provider once I eventually managed to implement it, but of which type is "registry" and where do I get it from?
First of all, here's a nice tutorial that came up a few days ago, which explains the basics of IntelliJ plugin development (you should take a look at the section Reference Contributor).
You will likely have to define your own PsiReferenceContributor, which will be referenced in your plugin.xml like this:
<psi.referenceContributor implementation="com.yourplugin.YourReferenceContributor"/>
In your reference contributor, there's a method registerReferenceProviders(PsiReferenceRegistrar) where you will be able to call registry.registerReferenceProvider(XmlTag.class, provider).
Finally, in your instance of PsiReferenceProvider, you will have to test the tag name to filter out tags which don't contain class references, then find the right Java class using JavaPsiFacade.findClass().
From my experience, the best place to get help regarding IntelliJ plugin development is JetBrains' forums.
i have created my own graphical editor using GMF.
i want to generate code based on the diagram created by editor? any pointers how to proceed
This might help you:
http://www.vogella.de/articles/EclipseBuilder/article.html
That page doesn't have the actual code example but the points to the necessary concepts: Builders. For example, the java compiler is hooked in through a builder that's registered for the .java type.
I'd love to ask you how do the guys developing dojo create the documentation?
From nightly builds you can get the uncompressed js files with all the comments, and I'm sure there is some kind documenting script that will generate some html or xml out of it.
I guess they use jsdoc as this can be found in their utils folder, but I have no idea on how to use it. jsDoc toolkit uses different /**commenting**/ notations than the original dojo files.
Thanks for all your help
It's all done with a custom PHP parser and Drupal. If you look in util/docscripts/README and util/jsdoc/INSTALL you can get all the gory details about how to generate the docs.
It's different than jsdoc-toolkit or JSDoc (as youv'e discovered).
FWIW, I'm using jsdoc-toolkit as it's much easier to generate static HTML and there's lots of documentation about the tags on the google code page.
Also, just to be clear, I don't develop dojo itself. I just use it a lot at work.
There are two parts to the "dojo jsdoc" process. There is a parser, written in PHP, which generates xml and/or json of the entirety of listed namespaces (defined in util/docscripts/modules, so you can add your own namespaces. There are basic usage instructions atop the file "generate.php") and a Drupal part called "jsdoc" which installs as a drupal module/plugin/whatever.
The Drupal aspect of it is just Dojo's basic view of this data. A well-crafted XSLT or something to iterate over the json and produce html would work just the same, though neither of these are provided by default (would love a contribution!). I shy away from the Drupal bit myself, though it has been running on api.dojotoolkit.org for some time now.
The doc parser is exposed so that you may use its inspection capabilities to write your own custom output as well. I use it to generate the Komodo .cix code completion in a [rather sloppy] PHP file util/docscripts/makeCix.php, which dumps information as found into an XML doc crafted to match the spec there. This could be modified to generate any kind of output you chose with a little finagling.
The doc syntax is all defined on the style guideline page:
http://dojotoolkit.org/reference-guide/developer/styleguide.html
Is there any kind of standard across editor and IDEs for expanding snippets?
Specifically, I would like to write a patch for an API that would provide a code snippet database that could be imported into different editors/IDEs and expand on demand.
I am writing something for vim (my editor of choice so that)
:expand theme_some_function
would then insert
/**
* Override of theme_some_function($&arg)
**/
MYMODULE_some_function(&$arg1) {
// contents of the function go here
}
which is how you override a function in Drupal.
Originally I was writing this so that it would go find the file through ctags and copy the function and s/foo/bar/ what needs to be changed. It was suggested that I could expand this to other editors, so I was wondering if there was a standard that I might use.
But in general, is there any kind of editor standard that might give me ideas about opportunities to write something for many editors at once?
There isn't really any such editor standard, no.
I've not found any such standard. But here are a few points for exploration.
• Microsoft publishes a spec for an XML-based format of code snippets.
Code Snippets Schema Reference (Visual Studio 2012)
• Wikipedia has an article on code snippets but makes no mention of standards.
• This web page for Code Collector Pro (Mac OS X app) mentions:
Support for .snippet Files – A new common file format for all snippet managers
…but provides no information or links about such a format.