I'm new to Doxygen and I'm trying to document an API I am planning to open source. I'd really like to build two sets of documentation, one for end users of the API and one for those who intend to modify it. Is there a way to tag Doxygen comment blocks in a way such that I can generate "user" and "dev" documentation trees? Is there a better solution to my problem? Thanks!
Depending on how your code is structured, you might be able to get away with using two Doxygen config files each including separate source files. The "user" config file would only list the source files containing the public interface to the API, while the "dev" config file would list all source files for the whole project.
This does mean that all your interfaces (e.g. abstract base classes) will need to be documented with the user in mind, but that is usually not a problem as by definition there is unlikely to be any implementation details in an abstract base class.
All your "dev" documentation then sits in the actual classes implementing the interfaces, which are never seen by the API and can be safely omitted by the "user" Doxygen config file.
Of course if your code isn't structured this way it's not going to work, so the only solution I can think of is to fill your comments with a bunch of conditional statements.
In addition to what Malvineous already said, there is the \internal doxygen command.
\internal lets you hide or show part of the documentation by changing INTERNAL_DOCS in the Doxyfile
More information here: http://www.doxygen.nl/manual/commands.html#cmdinternal
Related
In unreal engine, what is the difference between the two?
I could not find it in the API, just this: https://docs.unrealengine.com/5.0/en-US/gameplay-classes-in-unreal-engine/
I suspect that it adds .generated if you create the class from the Unreal editor, but I do not understand if it is any different with or without it.
Ah, so the .generated header is required inside the actual header file of the class (specifically as the last header).
https://forums.unrealengine.com/t/creating-classes-in-visual-studio/282386/4
Unreal has a code generation tool called "Unreal Header Tool" or UHT for short. During the build process of the project, it runs right before the actual compiler to generate code for the reflection, based on the UPROPERTY(), UFUNCTION(), etc. calls that you have in your code.
All that information is stored in two files: <Class>.generated.h and <Class>.generated.cpp
The header needs to be included last in the header to ensure that all references in a file are potentially valid in the generated code. Everything within the generated header file can be accessed via the UClass reflection system.
You can find the generated files in the "Intermediate/Build" directory of your project.
You can find the implementation of the UHT in the project on GitHub and a little more info about it in the docs.
Examples in the Zend tutorial:
phpunit.xml.dist
local.php.dist
TestConfig.php.dist
.dist files are often configuration files which do not contain the real-world deploy-specific parameters (e.g. Database Passwords, etc.), and are there to help you get started with the application/framework faster. So, to get started with such frameworks, you should remove the .dist extension, and customize your configuration file with your personal parameters.
One purpose I have seen in using .dist extension, is to avoid publishing personal data on VCSs (say git). So, you, as the developer of a reusable app, would use your own configuration file, but put the de-facto get-started config data in a separate .dist-suffixed file. (See Symfony2's documentation, 4th part)
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.
So far I have two short questions:
1) What precisely are the benefits of creating custom nature?
2) Is it possible to somehow programmatically read files in [project]/.setting or [workspace]/.metadata/.plugins?
I'm using Eclipse Helios (3.6).
Ad 1. I've read that you can't have two natures ofthe same set, that you can use it to associate certain perspectives/tools (ex. builder) with it but well.. anyting else I can't do easily without nature? Ex. I can easily add a builder by modifying an IProject variable.
Ad 2. I tried to find a way to read project specific settings or plugin settings but failed. No specs, different file types, inconsistent XML tags... Is it at all possible without parsing them manually?
Thanks for your help!
Paweł
Think of a nature as a flag. All project-related functionality in Eclipse is triggered by natures. Project properties pages, context menu items, etc. appear based on presence of natures. Third parties can check for presence of nature to tell if the project is of certain "type". A nature also has install/uninstall methods. This gives you a convenient place to implement all actions that need to happen on the project when your technology is enabled. Why is that convenient? Because a third party can simply add the nature without knowing what else is necessary to configure and your code takes care of the rest.
Plugins write to [project]/.setting or [workspace]/.metadata/.plugins locations in different ways. The file formats are never documented as they aren't meant to be manipulated directly. Some plugins re-use the common ProjectScope and InstanceScope classes to read/write the data. Some read/write on their own. I would start with what information you are trying to read, figure out which plugin it belongs to and then see if there is public API in that plugin for accessing that information. Reading these settings directly is almost never going to be the correct approach.
As suggested by the Eclipse documentation, I have an org.eclipse.core.resources.IncrementalProjectBuilder that compiles each source file and separately I also have a org.eclipse.ui.editors.text.TextEditor that can edit each source file. Each source file is compiled into its own compilation unit, but it can reference types from other (already compiled) source files.
Two tasks for which this is important are:
Compiling (to make sure the types we're using actually exist)
Autocomplete (to look up the type so we can see what properties/methods are present on it)
To accomplish this, I want to store a representation of all the compiled types in memory (referred to below as my "type store").
My question is two fold:
Task one above is performed by the builder and task two by the editor. So that they both have access to this type store, should I create a static store somewhere that they both can have access to, or does Eclipse provide a neater way to deal with this problem? Note that it is eclipse, not me, that instantiates the builders and editors when they are needed.
When opening eclipse, I don't want to have to rebuild the whole project just so I can re-populate my type store. My best solution so far is to persist this data somewhere and then repopulate my store from that (perhaps upon project open). Is this how other incremental compilers typically do this? I believe Java's approach is to use a special parser that efficiently extracts this data from the class files.
Any insights would be really appreciated. This is my first DSL.
This is an interesting question and one that doesn't have a simple solution. I'll try to describe a potential solution and also describe in a little bit more detail how JDT accomplishes incremental compilation.
First, a bit about JDT:
Yes, JDT does read class files for some of its information, but only for libraries that don't have source code. And this information is really only used for editing assistance (content assist, navigation, etc).
JDT computes incremental compilation by keeping track of dependencies between compilation units as they are compiled. This state information is stored on disk and retrieved and updated after each compile.
As a more complete example, let's say that after a full build, JDT determines that A.java depends on B.java, which depends on C.java.
If there is a structural change in C.java (a structural change is a change that can affect outside files (e.g., adding/removing a non-private field or method)), then B.java will be recompiled. A.java will not be recompiled since there was no structural change in B.java.
After this bit of clarification on how JDT works, here are some possible answers to your questions:
Yes. This must be done through statically accessible global objects. JDT does this through the JavaCore and JavaModelManager objects. If you don't want to use global singletons, then you can access to your type store available through your plugin's Bundle activator instance. The e4 project does allow dependency injection, which is probably even better (but is not really a part of the core Eclipse APIs).
I think persisting the information on the file system is your best bet. The only real way to determine incremental compile dependencies is to do a full build, so you need to persist the information somewhere. Again, this is how JDT does it. The information is stored in your workspaces' .metadata directory somewhere in the org.eclipse.core.resources plugin. You can have a look at the org.eclipse.jdt.internal.core.builder.State class to see the implementation.
So, this may not be the answer you are looking for, but I think this is the most promising way to approach your problem.