Hallo We switched to doxygen (1.8.14) for generating our documentation (C# -> Latex). We found some issues, i'm not sure whether or not these are bugs or expected behavior (or misconfiguration on our end). I know it is quite a list, feel free to answer in parts.
I have attached example code. More detailed information is provided with the
examples, a high level overview:
1) The detailed description (subsubsection) is always shown, even though
no <remarks /> tag is provided and ALWAYS_DETAILED_SEC = NO.
2) (latex source code) properties under Property Documentation do not
always start their \hbox{...} on a new line -> causes formatting issues.
3) Abstract classes are nor marked as abstract.
4) Constructors are marked as inline.
5) Namespace in <see cref=""> are not shortened even though
HIDE_SCOPE_NAMES = YES, i guess this is expected behavior?
6) The Additional Inherited Members is always shown even though it is empty
7) Internal classes are still present in the Classes list (under Namespace
references), even though doxygen is configured to ignore internals.
8) <inheritdoc/> does not work for properties and gives warnings for
functions (params and return type missing) (looks like this was reported
before: https://sourceforge.net/p/doxygen/discussion/130994/thread/0af65154/)
9) Namespaces are automatically made a hyperlink in the documentation, for
example: namespace Test.Exceptions -> will cause every occurrence of the word
"Exceptions", in the documentation, to be a hyperlink.
Some issues i could not reproduce/provide a minimal example for:
10) The parsing sometimes goes wrong when using \todo{}, i have had:
o Warning: error : return type of member XXX is not documented (warning
treated as error, aborting now) when using \todo{} in the remarks above the
returns tag.
o HTML generation: infinite loop/assert failure; same one as reported here:
http://doxygen.10944.n7.nabble.com/ASSERT-quot-0-quot-in-docparser-cpp-5747-td7738.html.
(removing \todo out of the documentation resolves this issue). This is on
Windows 7 (64bit).
11) I got Latex warnings about multiple defined labels.
Some additional findings/remarks:
12) Why is
\newcommand{\+}{\discretionary{\mbox{\scriptsize$\hookleftarrow$}}{}{}} defined
in the header.tex instead of the syl? (it won't work without defining the
command)
13) Why hijack \paragraph for Property Documentation entries? This may be
annoying if one wants to include a custom section (text) before the
documentation (if that uses \paragraph; or \subparagraph for that matter). You
can use the \usepackage{titlesec} package to define custom titles if so desired.
14) \usepackage{fixltx2e} in header.tex is no longer required or do you want
it to be compatible with older tex installations? (generates: fixltx2e Warning:
fixltx2e is not required with releases after 2015)
15) If one provides a custom header.tex and it ends with a comment (e.g. %---
Begin generated content ---) the first title will be missing. The first line of
the generated content will be appended, instead of starting on a new line, (and
thus be commented). Therefor the header.tex may not end on a comment.
I tried to filter out all already known issues. We also encountered these
(already reported) bugs:
16) https://bugzilla.gnome.org/show_bug.cgi?id=780439 -> i would expect both
classes to be in the list + in the documentation
17) https://bugzilla.gnome.org/show_bug.cgi?id=638606 (fixed)
18) https://bugzilla.gnome.org/show_bug.cgi?id=794509 (fixed)
19) https://bugzilla.gnome.org/show_bug.cgi?id=777746 (fixed)
Thanks in advance.
==============================================
"The information contained in this e-mail message may be confidential
information, and may also be privileged. If you are not the intended recipient,
any use, interference with, disclosure or copying of this material is
unauthorised and prohibited. If you have received this message in error, please
notify us by return email and delete the original message."
ATT79970.doxyfile_general
Description: ATT79970.doxyfile_general
using System;
namespace DoxygenDemo
{
// ==============================================================
// There is always a (empty) detailed description (even with
ALWAYS_DETAILED_SEC = NO).
// Expected: empty detailed description (subsub)sections are not generated
/// <summary>
/// Demo: This class only has brief but no detailed description.
/// </summary>
public class DetailedSection
{
}
// ==============================================================
// In Latex source code the properties (under Property Documentation) do
sometimes not have a new line between them.
// The \mbox{\Hypertarget{...}} is placed directly after the detailed
description of the previous property,
// instead of on a new line. See file a00560.tex
//
// Due to the large vertical white spaces between properties (defined by the
default Latex header; \paragraph redefinition) you will
// likely never notice but we have a custom header to have a more compact
document. In our document it is very obvious.
//
// Expected: there the \mbox{\Hypertarget{...}} at the start of a property
is always on a new line
/// <summary>
/// Demo: The properties do not have a newline between them in latex (source
code).
/// </summary>
public class PropertySpacingIsssue
{
/// <summary>
/// The selected
/// </summary>
public string Property2 { get; }
/// <summary>
/// The first property.
/// </summary>
/// <remarks>
/// This is a description with some lines.
/// Of text that are a bit elaborate but that's about it.
/// </remarks>
public string Property1 { get; }
}
// ==============================================================
// Abstract classes are not marked as abstract in the documentation
// Expected: the class is marked as abstract
/// <summary>
/// Demo: In latex this class will not show as abstract.
/// </summary>
public abstract class MyAbstractClass
{
/// <summary>
/// My summery
/// </summary>
/// <param name="value">A value to pass</param>
public MyAbstractClass(string value)
{
}
}
// ==============================================================
// Constructor is marked as inline
// Expected: the constructor is not marked as inline
/// <summary>
/// Demo: In latex this class will not show as abstract.
/// </summary>
public class InlineConstructor
{
/// <summary>
/// Demo: why is this marked as inline under Constructor & Destructor
documentation?
/// </summary>
/// <param name="value">A value to pass</param>
public InlineConstructor(string value)
{
}
}
// ==============================================================
// Namespace in cref are not shortened even though HIDE_SCOPE_NAMES = YES
// Is this expected behavior or not?
/// <summary>
/// Test <see cref="DoxygenDemo.MyAbstractClass"/>, will include the
namespace.
/// </summary>
public class NamespaceTruncation
{
}
// ==============================================================
// Additional Inherited Members is generated while it is empty
// Expected: the section is omitted if not applicable.
/// <summary>
/// The brief
/// </summary>
public interface IMyInterface
{
/// <summary>
/// THe brief2
/// </summary>
void MyFunction();
}
/// <summary>
/// DEMO: empty additional inherited members section
/// </summary>
public interface IMyInterface2 : IMyInterface
{
}
// ==============================================================
// Internal classes should not be document, still this class will be
// included in the class overview.
// This issue seems to be old, report here:
https://stackoverflow.com/questions/1862318/doxygen-with-c-sharp-internal-access-modifier
// (look at the answer of Stevens Miller)
// Is there an official work around or how should doxygen be configured?
// Expected: the class is not present in the class list
//
// Additionally: the documentation is not properly generated for this
example -> see pdf
///<summary>
/// Provides support for extracting property information based on a property
expression.
///</summary>
internal static class MyStaticClass
{
}
// ==============================================================
// <inheritdoc/> does not seem to work (it adds nothing to the generated PDF)
// Expected: the documentation would be repeated or there would be a
reference to the original documentation
/// <summary>
/// By documentation
/// </summary>
public interface IMyInterface3
{
/// <summary>
/// My documentation
/// </summary>
/// <returns>The return value</returns>
string MyFunction();
/// <summary>
/// My documented property
/// </summary>
/// <remarks>
/// My remarks
/// </remarks>
string MyProperty { get; }
}
/// <summary>
/// DEMO: <inheritdoc/> issues
/// </summary>
public class InheritdocDoesNotWork : IMyInterface3
{
/// <inheritdoc/>
// This generates a warning about the return type not being documented. I
guess this is expected?
// Warnings will also trigger for parameters
public string MyFunction()
{
throw new NotImplementedException();
}
/// <inheritdoc/>
// Documentation is missing for this property
public string MyProperty { get; }
}
// ==============================================================
// Classes with the same name (1 generic and 1 not) do not show up in the
documentation
// Expectation: both classes are threated as different classes and both show
up
//
// There was already a bug report for this:
https://bugzilla.gnome.org/show_bug.cgi?id=780439
/// <summary>
/// My generic implementation
/// </summary>
/// <typeparam name="T">The type</typeparam>
public class MyRealClass<T>
{
}
/// <summary>
/// My normal implementation
/// </summary>
// Note: This class will not show up in the documentation
// Note: This class will show up in the class list (DoxygenDemo Namespace
Reference) and the generic one will not
public class MyRealClass
{
}
// ==============================================================
// Namespaces are automatically made a hyperlink
// Expected: only when using <see cref=""> you will get a hyperlink
otherwise it is normal text.
/// <summary>
/// My documentation
/// </summary>
namespace Exceptions
{
/// <summary>
/// DEMO: if i use the word. Exceptions in the documentation it is a
hyperlink.
/// </summary>
// The word "Exceptions" will become a hyperlink
public class MyException : Exception
{
}
}
}
------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________ Doxygen-users mailing list Doxygen-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/doxygen-users
