I may be missing something obvious, but I can't get Scaladoc to link to classes—only to companion objects. Consider these examples.
This works fine:
/** Returns a [[scala.List]] (also known as [[scala.collection.immutable.List]]). */
While this won't link, with Could not find any member to link for "play.api.libs.json.JsObject" logged as a warning:
/** Seems [[play.api.libs.json.JsObject]] is invalid. */
This (taking into account disambiguation syntax), however, will link:
/** Seems [[play.api.libs.json.JsObject$]] is liked. */
I've got external API mappings sorted out in SBT and generated documentation of function signatures links correctly to external site, so I'm (fairly) certain this isn't related to my problem.
Where am I going wrong? (Or is this a bug?)
Related
I am new to Doxygen but I want to use it for a technical documentation for our team.
The background: We have several services in .NET which are going to be called from a JAVA backend through RPC.
Therefore it is quite useful to have those services documented for the JAVA guys.
Using the Doxywizard did help in the first place, but it created a huge overflow of data, which I want to filter, but have no clue how to.
What I want to achieve is, that Doxygen ONLY will use methods, which does have a specific attribute.
For example:
[RpcMethod(id: "GetNumDemo", description: "A demo method")]
public async Task<int> GetNumDemo(JavaDTO dtoObject, int randNum)
I want to have the method within the documentation found by Doxygen since it has the RpcMethod attribute and also cause it have a JavaDTO object, I want to have this class documented as well.
But I am overwhelmed with it ... do you guys can help me? ... at least with a hint within the Doxygen documentation.
Read through the documentation and goodled
The company I'm working for does not use Doxygen, and in their coding standard explicitly prohibits "parseable comment styles such as javadoc, etc".
However, I've still found it very useful to run Doxygen myself just so I can see the class structure, and get nice per-class documentation of all the methods the a class has, including inherited ones.
The company does document the classes in the header files, with simple comments above each method declaration. It would be very useful if I could configure Doxygen to treat these comments as the function descriptions, even though they don't start with any Doxygen markers.
So: is it possible to get Doxygen to treat comments on the line above declarations as if they are the description for that item even when the comment is not marked with Doxygen's "parse this comment" markers?
The next best thing is to click on the #include <foo.h> links at the top of the class file to jump to the file itself, which I have been using. That doesn't help for seeing all of a derived class's methods in one place, though.
When the comments above the methods have only "normal" comments i.e. with /* or // the best thing to do would be that you write a small filter (see e.g. INPUT_FILTER with sed or awk or ... ) in which you convert (all?) /* / // comments into /** / /// so the comment blocks are parsed by doxygen. The result is not as nice as with "full" doxygen comments.
It is just a workaround and can lead to unexpected results when the INPUT_FILTER does not exclude e.g. // inside strings from consideration.
Im upgrading an extension to work with TYPO3 v10. Since command controllers can not be used anymore, im migrating them to symfony commands as pointed by the documentation. Everything works smooth as heck except for the usage of extbase repository classes. No matter what i query, i never get a result. Since i can't find any useful information on the web and the documentation i hope this may be just something minor.
After debugging for a while i found out that the pid is not determined correctly while building the query settings. I find that kind of strange since my root template has these lines:
plugin.tx_myext.persistence.storagePid = 15403
module.tx_myext.persistence.storagePid = 15403
The repository instances are correctly injected by injectMyRepository() methods. I've tried using the extbase ObjectManager to fetch the class instances instead but the "error" stays the same.
Am i doing something wrong or is it not possible to use extbase repository classes in symfony commands?
After more research i found out that there is some bootstraping missing which results in extension settings (the storageID in my case) not being loaded. From what i've been reading, that behaviour seems intended to prevent extbase booting, i guess?
There is a reference to something similiar in the official documentation: https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/ApiOverview/CommandControllers/Index.html#initialize-backend-user
Knowing that, i tried to find a method to initialize the missing settings which i could not find. So this does indeed seem like a missing feature.
I developed a workaround which i'm not too proud of, but it's better than nothing (or rebuilding everything to doctrine for that matter). If you stumble upon the same issue, here you go. Just insert and call this method before you fire your query:
public static function initializeConfigurationManager(): void
{
/** #var ConfigurationManager $configurationManager */
$configurationManager = GeneralUtility::makeInstance(ConfigurationManager::class);
$tmpConfiguration = $configurationManager->getConfiguration(
ConfigurationManagerInterface::CONFIGURATION_TYPE_FRAMEWORK,
'myExtensionName'
);
$configurationManager->setConfiguration($tmpConfiguration);
}
That approach exploits the singleton state of the ConfigurationManager. You simply inject the static template of your extension manually and every extbase compound (like repositories) will then use these settings from there on. Lovely.
Be aware however, this is prone to break with future internal changes.
I binged or googled for scaladoc 2.0 tutorial or example, I could not find anything, in fact not even a link to official scaladoc 2.0 documentation.
Anyone know where to find one?
docs.scala-lang.org is a more recent source of "Community-driven documentation for Scala" (thanks to the initiative lead by Heather Miller).
(as edited by Martin Konicek in David James's original answer)
The Scaladoc page is quite up-to-date.
Martin Konicek asks in the comment how to make a simple Javadoc-like {#link}.
(And {#link} isn't mentioned in scala.tools.nsc.ast.DocComments.scala)
He mentions that Scaladoc uses [[fullyQualifiedName]] instead of {#link}.
Initial answer (July/Sept 2011)
Right now, the most complete source of information I know about Scaladoc2 is in the new scala-lang.org Wiki.
David James mentions in the comments the Syntax page, and the Tags and Annotations.
The author page has examples, including a what's new section:
Authors of documentation no longer have to use HTML tags in their comments.
Instead, Scaladoc supports a wiki-like syntax very similar to that used in Trac.
In general, Scaladoc authors should no longer use HTML tags in documentation as Scaladoc may in the future also generate documentation in other formats than HTML.
I wrote a Scaladoc HOWTO over on github here.
It's a how-to written with Scaladoc itself so it serves as an example. I placed extra emphasis on how to get the package documentation to show up in your API, as this is not very clear in the official documentation.
The Scala Style Guide has a nice introductory page on scaladoc. I'd recommend it over the scala-lang.org wiki mentioned in #VonC's answer.
A condensed full example:
/** Creates [[mypackage.Person]] instances, taking a `String` argument. */
object Person {
/** Create a [[mypackage.Person]] with a given name.
*
* This is another paragraph (note the empty line above) containing '''bold''',
* ''italic'', `monospace`, __underline__, ^superscript^, and ,,subscript,,.
*
* Example:
* {{{
* val person = Person("Bill")
* }}}
*
* #param name their name
* #return a new Person instance
*/
def apply(name: String) = {}
}
Note that Scaladoc 2.9 does not support [[links]] to methods (like Javadoc's {#link type#instanceMethod(int, String)} or {#link type.staticMethod()}).
This is the best Scaladoc guide I have found: https://gist.github.com/VladUreche/8396624. It is markdown text, so download it and use a markdown viewer plugin for your browser or paste it into http://markdownlivepreview.com/ to read it.
I am building a Qt based project, and many Qt classes are found in the target documentation.
How can I tell Doxygen to disable documentation generation for some classes? For Q.*?
Working under the assumption that what you have is something like this: (The question is a little unclear in this regard)
/**
* Some documentation for class X
*/
class X: public osg::Drawable {
...
}
And your problem is that you want to include documentation for class X, but not for class osg::Drawable, the proper technique is to use EXCLUDE_SYMBOLS. For example, in the case above use
EXCLUDE_SYMBOLS = osg::Drawable
If you want to be slightly more rigorous, you can use
EXCLUDE_SYMBOLS = osg::Drawable \
Drawable
Wild-cards are also allowed, so this will also work
EXCLUDE_SYMBOLS = osg::*
If \internal tag does not work, you can try \cond ... \endcond tags for marking a portion of code to be hidden from Doxygen.
EDIT
If you want to exclude specific files, you can use EXCLUDE_PATTERNS variable in Doxyfile configuration file.
Its not the best way but one can mark some portion of the documentation (class, members, ...) with the private. This prevents the piece of code from being included in the output documentation. (I use this to hide copy/move constructors/operators from appearing in the API documentation.)
/*!
* \brief This is included.
*/
class API
{
public:
/*!
* \brief So is this.
*/
API() noexcept;
/// \private
~API() noexcept; /* But this not, though technically public. */
private:
int m_version; /* This is not either. */
}
One should note though that this is a Doxygen extension for PHP, which according to the documentation they should not be used.
For PHP files there are a number of additional commands, that can be used inside classes to make members public, private, or protected even though the language itself doesn't support this notion.
The other option is to use the solution mouviciel provided, but it requires at least two lines.
Though not the correct answer for the detailed question it might be helpful for readers of the question title (like me). It works for classe too!