Opened 16 months ago

Closed 13 months ago

Last modified 7 months ago

#15346 closed defect (fixed)

Fix Doxygen errors

Reported by: vadz Owned by:
Priority: low Milestone: 3.0.0
Component: documentation Version: 2.9.5
Keywords: doxygen Cc:
Blocked By: Blocking:
Patch: no

Description

There are quite a few Doxygen errors in the log file created by running regen.bat chm in docs/doxygen (notice that you need to use Doxygen 1.8.2 to not get any other errors), see below.

It would be nice to fix them before 3.0 and to check that no warnings are given for the 3.0 docs build. Any help with doing this would be welcome, TIA!

The log:

interface/wx/utils.h:602: warning: end of comment block while expecting command </code>
interface/wx/utils.h:602: warning: end of comment block while expecting command </code>
interface/wx/affinematrix2d.h:95: warning: Found unknown command `\t'
interface/wx/affinematrix2d.h:85: warning: Found unknown command `\t'
interface/wx/affinematrix2d.h:85: warning: Found unknown command `\t'
interface/wx/affinematrix2dbase.h:128: warning: Found unknown command `\t'
interface/wx/affinematrix2dbase.h:118: warning: Found unknown command `\t'
interface/wx/affinematrix2dbase.h:118: warning: Found unknown command `\t'
interface/wx/affinematrix2d.h:85: warning: Found unknown command `\t'
interface/wx/affinematrix2d.h:95: warning: Found unknown command `\t'
interface/wx/affinematrix2d.h:85: warning: Found unknown command `\t'
interface/wx/affinematrix2dbase.h:128: warning: Found unknown command `\t'
interface/wx/affinematrix2dbase.h:118: warning: Found unknown command `\t'
interface/wx/affinematrix2dbase.h:118: warning: Found unknown command `\t'
interface/wx/affinematrix2dbase.h:118: warning: Found unknown command `\t'
interface/wx/affinematrix2dbase.h:128: warning: Found unknown command `\t'
interface/wx/affinematrix2dbase.h:118: warning: Found unknown command `\t'
interface/wx/affinematrix2dbase.h:189: warning: argument 'p' of command @param is not found in the argument list of wxAffineMatrix2DBase::TransformDistance(const wxPoint2DDouble &src) const
interface/wx/affinematrix2dbase.h:189: warning: The following parameters of wxAffineMatrix2DBase::TransformDistance(const wxPoint2DDouble &src) const are not documented:
  parameter 'src'
interface/wx/affinematrix2dbase.h:178: warning: argument 'p' of command @param is not found in the argument list of wxAffineMatrix2DBase::TransformPoint(const wxPoint2DDouble &src) const
interface/wx/affinematrix2dbase.h:178: warning: The following parameters of wxAffineMatrix2DBase::TransformPoint(const wxPoint2DDouble &src) const are not documented:
  parameter 'src'
interface/wx/commandlinkbutton.h:153: warning: image file appear-commandlinkbutton-mac.png is not found in IMAGE_PATH: assuming external image.
interface/wx/control.h:92: warning: The following parameters of wxControl::wxControl(wxWindow *parent, wxWindowID id, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxControlNameStr) are not documented:
  parameter 'validator'
interface/wx/dir.h:259: warning: explicit link request to 'wxFILE_SEP_PATH' could not be resolved
interface/wx/dir.h:268: warning: explicit link request to 'wxFILE_SEP_PATH' could not be resolved
interface/wx/event.h:490: warning: argument 'x2' of command @param is not found in the argument list of wxEvtHandler::CallAfter(void(T::*method)(T1,...), T1 x1,...)
interface/wx/filectrl.h:59: warning: image file appear-filectrl-msw.png is not found in IMAGE_PATH: assuming external image.
interface/wx/filectrl.h:63: warning: image file appear-filectrl-mac.png is not found in IMAGE_PATH: assuming external image.
interface/wx/valnum.h:309: warning: argument 'precision' of command @param is not found in the argument list of wxFloatingPointValidator< T >::wxFloatingPointValidator(ValueType *value=NULL, int style=wxNUM_VAL_DEFAULT)
interface/wx/dirctrl.h:57: warning: found </div> tag without matching <div>
interface/wx/dirctrl.h:63: warning: found </div> at different nesting level (7) than expected (5)
interface/wx/dirctrl.h:66: warning: end of comment block while expecting command </div>
interface/wx/dirctrl.h:66: warning: end of comment block while expecting command </div>
interface/wx/graphics.h:1346: warning: argument 'radians' of command @param is not found in the argument list of wxGraphicsMatrix::Rotate(wxDouble angle)
interface/wx/graphics.h:1346: warning: The following parameters of wxGraphicsMatrix::Rotate(wxDouble angle) are not documented:
  parameter 'angle'
interface/wx/event.h:3438: warning: explicit link request to 'wxHelpEventOrigin' could not be resolved
interface/wx/event.h:3438: warning: explicit link request to 'wxHelpEventOrigin' could not be resolved
interface/wx/event.h:3438: warning: explicit link request to 'wxHelpEventOrigin' could not be resolved
interface/wx/html/helpctrl.h:196: warning: Found unknown command `\enable'
interface/wx/iconbndl.h:117: warning: explicit link request to 'FALLBACK_NONE' could not be resolved
interface/wx/iconbndl.h:118: warning: explicit link request to 'FALLBACK_SYSTEM' could not be resolved
interface/wx/iconbndl.h:121: warning: explicit link request to 'FALLBACK_NEAREST_LARGER' could not be resolved
interface/wx/listctrl.h:1538: warning: image file appear-listview-msw.png is not found in IMAGE_PATH: assuming external image.
interface/wx/listctrl.h:1542: warning: image file appear-listview-mac.png is not found in IMAGE_PATH: assuming external image.
interface/wx/intl.h:452: warning: argument 'short' of command @param is not found in the argument list of wxLocale::Init(const wxString &name, const wxString &shortName=wxEmptyString, const wxString &locale=wxEmptyString, bool bLoadDefault=true)
interface/wx/intl.h:452: warning: The following parameters of wxLocale::Init(const wxString &name, const wxString &shortName=wxEmptyString, const wxString &locale=wxEmptyString, bool bLoadDefault=true) are not documented:
  parameter 'shortName'
interface/wx/msgdlg.h:33: warning: found </div> at different nesting level (7) than expected (5)
interface/wx/msgdlg.h:76: warning: found </div> at different nesting level (7) than expected (5)
interface/wx/msgdlg.h:92: warning: end of comment block while expecting command </div>
interface/wx/msgdlg.h:92: warning: end of comment block while expecting command </div>
interface/wx/event.h:3854: warning: explicit link request to 'wxNavigationKeyEventFlags' could not be resolved
interface/wx/ribbon/toolbar.h:328: warning: argument 'toolId' of command @param is not found in the argument list of wxRibbonToolBar::GetToolClientData(int tool_id) const
interface/wx/ribbon/toolbar.h:328: warning: The following parameters of wxRibbonToolBar::GetToolClientData(int tool_id) const are not documented:
  parameter 'tool_id'
interface/wx/ribbon/toolbar.h:340: warning: argument 'toolId' of command @param is not found in the argument list of wxRibbonToolBar::GetToolEnabled(int tool_id) const
interface/wx/ribbon/toolbar.h:340: warning: The following parameters of wxRibbonToolBar::GetToolEnabled(int tool_id) const are not documented:
  parameter 'tool_id'
interface/wx/ribbon/toolbar.h:354: warning: argument 'toolId' of command @param is not found in the argument list of wxRibbonToolBar::GetToolHelpString(int tool_id) const
interface/wx/ribbon/toolbar.h:354: warning: The following parameters of wxRibbonToolBar::GetToolHelpString(int tool_id) const are not documented:
  parameter 'tool_id'
interface/wx/ribbon/toolbar.h:364: warning: argument 'toolId' of command @param is not found in the argument list of wxRibbonToolBar::GetToolKind(int tool_id) const
interface/wx/ribbon/toolbar.h:364: warning: The following parameters of wxRibbonToolBar::GetToolKind(int tool_id) const are not documented:
  parameter 'tool_id'
interface/wx/ribbon/toolbar.h:374: warning: argument 'toolId' of command @param is not found in the argument list of wxRibbonToolBar::GetToolPos(int tool_id) const
interface/wx/ribbon/toolbar.h:374: warning: The following parameters of wxRibbonToolBar::GetToolPos(int tool_id) const are not documented:
  parameter 'tool_id'
interface/wx/ribbon/toolbar.h:385: warning: argument 'toolId' of command @param is not found in the argument list of wxRibbonToolBar::GetToolState(int tool_id) const
interface/wx/ribbon/toolbar.h:385: warning: The following parameters of wxRibbonToolBar::GetToolState(int tool_id) const are not documented:
  parameter 'tool_id'
interface/wx/ribbon/toolbar.h:422: warning: argument 'id' of command @param is not found in the argument list of wxRibbonToolBar::SetToolClientData(int tool_id, wxObject *clientData)
interface/wx/ribbon/toolbar.h:422: warning: The following parameters of wxRibbonToolBar::SetToolClientData(int tool_id, wxObject *clientData) are not documented:
  parameter 'tool_id'
  parameter 'clientData'
interface/wx/ribbon/toolbar.h:432: warning: The following parameters of wxRibbonToolBar::SetToolDisabledBitmap(int tool_id, const wxBitmap &bitmap) are not documented:
  parameter 'bitmap'
interface/wx/ribbon/toolbar.h:443: warning: argument 'tool_Id' of command @param is not found in the argument list of wxRibbonToolBar::SetToolHelpString(int tool_id, const wxString &helpString)
interface/wx/ribbon/toolbar.h:443: warning: The following parameters of wxRibbonToolBar::SetToolHelpString(int tool_id, const wxString &helpString) are not documented:
  parameter 'tool_id'
interface/wx/ribbon/toolbar.h:457: warning: The following parameters of wxRibbonToolBar::SetToolNormalBitmap(int tool_id, const wxBitmap &bitmap) are not documented:
  parameter 'bitmap'
interface/wx/richtext/richtextctrl.h:497: warning: The following parameters of wxRichTextCtrl::SetFocusObject(wxRichTextParagraphLayoutBox *obj, bool setCaretPosition=true) are not documented:
  parameter 'obj'
interface/wx/richtext/richtextctrl.h:2291: warning: argument 'id' of command @param is not found in the argument list of wxRichTextEvent::wxRichTextEvent(wxEventType commandType=wxEVT_NULL, int winid=0)
interface/wx/richtext/richtextctrl.h:2291: warning: The following parameters of wxRichTextEvent::wxRichTextEvent(wxEventType commandType=wxEVT_NULL, int winid=0) are not documented:
  parameter 'winid'
interface/wx/richtext/richtextbuffer.h:2087: warning: Found unknown command `\rect'
interface/wx/richtext/richtextbuffer.h:3566: warning: Found unknown command `\rect'
interface/wx/richtext/richtextbuffer.h:3667: warning: argument 'parent' of command @param is not found in the argument list of wxRichTextFieldTypeStandard::wxRichTextFieldTypeStandard(const wxString &name, const wxString &label, int displayStyle=wxRICHTEXT_FIELD_STYLE_RECTANGLE)
interface/wx/richtext/richtextbuffer.h:3667: warning: The following parameters of wxRichTextFieldTypeStandard::wxRichTextFieldTypeStandard(const wxString &name, const wxString &label, int displayStyle=wxRICHTEXT_FIELD_STYLE_RECTANGLE) are not documented:
  parameter 'name'
interface/wx/richtext/richtextbuffer.h:3683: warning: argument 'parent' of command @param is not found in the argument list of wxRichTextFieldTypeStandard::wxRichTextFieldTypeStandard(const wxString &name, const wxBitmap &bitmap, int displayStyle=wxRICHTEXT_FIELD_STYLE_NO_BORDER)
interface/wx/richtext/richtextbuffer.h:3683: warning: argument 'label' of command @param is not found in the argument list of wxRichTextFieldTypeStandard::wxRichTextFieldTypeStandard(const wxString &name, const wxBitmap &bitmap, int displayStyle=wxRICHTEXT_FIELD_STYLE_NO_BORDER)
interface/wx/richtext/richtextbuffer.h:3683: warning: The following parameters of wxRichTextFieldTypeStandard::wxRichTextFieldTypeStandard(const wxString &name, const wxBitmap &bitmap, int displayStyle=wxRICHTEXT_FIELD_STYLE_NO_BORDER) are not documented:
  parameter 'name'
  parameter 'bitmap'
interface/wx/richtext/richtextbuffer.h:3731: warning: Found unknown command `\rect'
interface/wx/richtext/richtextbuffer.h:2087: warning: Found unknown command `\rect'
interface/wx/richtext/richtextbuffer.h:2087: warning: Found unknown command `\rect'
interface/wx/richtext/richtextbuffer.h:2087: warning: Found unknown command `\rect'
interface/wx/richtext/richtextbuffer.h:2087: warning: Found unknown command `\rect'
interface/wx/richtext/richtextbuffer.h:2087: warning: Found unknown command `\rect'
interface/wx/richtext/richtextprint.h:343: warning: Found unknown command `\showPrintDialog'
interface/wx/richtext/richtextprint.h:349: warning: Found unknown command `\showPrintDialog'
interface/wx/richtext/richtextbuffer.h:2087: warning: Found unknown command `\rect'
interface/wx/simplebook.h:132: warning: unable to resolve reference to `page_libs_none' for \ref command
interface/wx/htmllbox.h:197: warning: image file appear-simplehtmllistbox-msw.png is not found in IMAGE_PATH: assuming external image.
interface/wx/htmllbox.h:201: warning: image file appear-simplehtmllistbox-mac.png is not found in IMAGE_PATH: assuming external image.
interface/wx/stopwatch.h:25: warning: explicit link request to 'QueryPerformanceCounter()' could not be resolved
interface/wx/stc/stc.h:3736: warning: Found unknown command `\d'
interface/wx/stc/stc.h:4083: warning: End of list marker found without any preceding list items
interface/wx/stc/stc.h:3736: warning: Found unknown command `\d'
interface/wx/stc/stc.h:3738: warning: Found unknown command `\d'
interface/wx/stc/stc.h:3741: warning: Found unknown command `\d'
interface/wx/stc/stc.h:5566: warning: explicit link request to 'RRGGBB' could not be resolved
interface/wx/stc/stc.h:5567: warning: explicit link request to 'RRGGBB' could not be resolved
interface/wx/stc/stc.h:5796: warning: unable to resolve reference to `page_libs_stc' for \ref command
interface/wx/dcsvg.h:101: warning: Unsupported xml/html tag <g> found
interface/wx/dcsvg.h:71: warning: Unsupported xml/html tag <g> found
interface/wx/textctrl.h:1307: warning: argument 'col' of command @param is not found in the argument list of wxTextCtrl::HitTest(const wxPoint &pt, long *pos) const
interface/wx/textctrl.h:1307: warning: argument 'row' of command @param is not found in the argument list of wxTextCtrl::HitTest(const wxPoint &pt, long *pos) const
interface/wx/textctrl.h:1307: warning: argument 'pos' of command @param is not found in the argument list of wxTextCtrl::HitTest(const wxPoint &pt, wxTextCoord *col, wxTextCoord *row) const
interface/wx/thread.h:1220: warning: explicit link request to 'wxPRIORITY_MIN' could not be resolved
interface/wx/thread.h:1221: warning: explicit link request to 'wxPRIORITY_DEFAULT' could not be resolved
interface/wx/thread.h:1222: warning: explicit link request to 'wxPRIORITY_MAX' could not be resolved
interface/wx/thread.h:1255: warning: argument 'waitMode' of command @param is not found in the argument list of wxThread::Wait(wxThreadWait flags=wxTHREAD_WAIT_BLOCK)
interface/wx/thread.h:1255: warning: The following parameters of wxThread::Wait(wxThreadWait flags=wxTHREAD_WAIT_BLOCK) are not documented:
  parameter 'flags'
interface/wx/toolbar.h:884: warning: The following parameters of wxToolBar::SetToolClientData(int id, wxObject *clientData) are not documented:
  parameter 'clientData'
interface/wx/toolbar.h:890: warning: The following parameters of wxToolBar::SetToolDisabledBitmap(int id, const wxBitmap &bitmap) are not documented:
  parameter 'bitmap'
interface/wx/toolbar.h:920: warning: The following parameters of wxToolBar::SetToolNormalBitmap(int id, const wxBitmap &bitmap) are not documented:
  parameter 'bitmap'
interface/wx/treelist.h:454: warning: The following parameters of wxTreeListCtrl::InsertItem(wxTreeListItem parent, wxTreeListItem previous, const wxString &text, int imageClosed=NO_IMAGE, int imageOpened=NO_IMAGE, wxClientData *data=NULL) are not documented:
  parameter 'text'
interface/wx/webview.h:329: warning: The following parameters of wxWebView::New(wxWindow *parent, wxWindowID id, const wxString &url=wxWebViewDefaultURLStr, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, const wxString &backend=wxWebViewBackendDefault, long style=0, const wxString &name=wxWebViewNameStr) are not documented:
  parameter 'style'
  parameter 'name'
interface/wx/webview.h:151: warning: The following parameters of wxWebViewFactory::Create(wxWindow *parent, wxWindowID id, const wxString &url=wxWebViewDefaultURLStr, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=0, const wxString &name=wxWebViewNameStr)=0 are not documented:
  parameter 'style'
  parameter 'name'
interface/wx/wizard.h:251: warning: argument 'next' of command @param is not found in the argument list of wxWizardPageSimple::Chain(wxWizardPageSimple *first, wxWizardPageSimple *second)
interface/wx/wizard.h:251: warning: The following parameters of wxWizardPageSimple::Chain(wxWizardPageSimple *first, wxWizardPageSimple *second) are not documented:
  parameter 'first'
  parameter 'second'

Change History (16)

comment:1 Changed 15 months ago by csomor

I've fixed the wrong parameter name in wxGraphicsMatrix::Rotate in r74552

comment:2 Changed 15 months ago by SJL

(In [74575]) Fix wxWebView documentation warnings.

See #15346.

comment:3 Changed 14 months ago by SJL

(In [74688]) Fix warnings in rich text documentation.

See #15346.

comment:4 Changed 14 months ago by SJL

(In [74689]) Fix html documentation warnings.

See #15346.

comment:5 Changed 14 months ago by SJL

(In [74690]) Fix ribbon documentation warnings.

See #15346.

comment:6 Changed 14 months ago by SJL

(In [74691]) Fix various documentation warnings throughout core and base.

See #15346.

comment:7 Changed 14 months ago by steve_lamerton

  • Status changed from new to infoneeded_new

Most of these warnings are now fixed, I am not sure what to do about the remaining issues:

interface/wx/dirctrl.h:56: warning: found </div> tag without matching <div>
interface/wx/dirctrl.h:62: warning: found </div> at different nesting level (7) than expected (5)
interface/wx/dirctrl.h:65: warning: end of comment block while expecting command </div>
interface/wx/dirctrl.h:65: warning: end of comment block while expecting command </div>
interface/wx/msgdlg.h:32: warning: found </div> at different nesting level (7) than expected (5)
interface/wx/msgdlg.h:75: warning: found </div> at different nesting level (7) than expected (5)
interface/wx/msgdlg.h:91: warning: end of comment block while expecting command </div>
interface/wx/msgdlg.h:91: warning: end of comment block while expecting command </div>

Seems to be an issue with using @since inside an event or style list.

interface/wx/listctrl.h:1537: warning: image file appear-listview-msw.png is not found in IMAGE_PATH: assuming external image.
interface/wx/listctrl.h:1541: warning: image file appear-listview-mac.png is not found in IMAGE_PATH: assuming external image.
interface/wx/htmllbox.h:196: warning: image file appear-simplehtmllistbox-msw.png is not found in IMAGE_PATH: assuming external image.
interface/wx/htmllbox.h:200: warning: image file appear-simplehtmllistbox-mac.png is not found in IMAGE_PATH: assuming external image.
interface/wx/filectrl.h:58: warning: image file appear-filectrl-msw.png is not found in IMAGE_PATH: assuming external image.
interface/wx/filectrl.h:62: warning: image file appear-filectrl-mac.png is not found in IMAGE_PATH: assuming external image.
interface/wx/commandlinkbutton.h:152: warning: image file appear-commandlinkbutton-mac.png is not found in IMAGE_PATH: assuming external image.

Missing screenshots.

interface/wx/stc/stc.h:3736: warning: Found unknown command `\d'
interface/wx/stc/stc.h:4083: warning: End of list marker found without any preceding list items
interface/wx/stc/stc.h:3736: warning: Found unknown command `\d'
interface/wx/stc/stc.h:3738: warning: Found unknown command `\d'
interface/wx/stc/stc.h:3741: warning: Found unknown command `\d'
interface/wx/stc/stc.h:5566: warning: explicit link request to 'RRGGBB' could not be resolved
interface/wx/stc/stc.h:5567: warning: explicit link request to 'RRGGBB' could not be resolved
interface/wx/stc/stc.h:5796: warning: unable to resolve reference to `page_libs_stc' for \ref command

I am not sure where to fix these, it wasn't clear to me how the stc documentation is generated.

interface/wx/valnum.h:309: warning: argument 'precision' of command @param is not found in the argument list of wxFloatingPointValidator< T >::wxFloatingPointValidator(ValueType *value=NULL, int style=wxNUM_VAL_DEFAULT)
interface/wx/textctrl.h:1306: warning: argument 'col' of command @param is not found in the argument list of wxTextCtrl::HitTest(const wxPoint &pt, long *pos) const
interface/wx/textctrl.h:1306: warning: argument 'row' of command @param is not found in the argument list of wxTextCtrl::HitTest(const wxPoint &pt, long *pos) const
interface/wx/textctrl.h:1306: warning: argument 'pos' of command @param is not found in the argument list of wxTextCtrl::HitTest(const wxPoint &pt, wxTextCoord *col, wxTextCoord *row) const
interface/wx/event.h:489: warning: argument 'x2' of command @param is not found in the argument list of wxEvtHandler::CallAfter(void(T::*method)(T1,...), T1 x1,...)

Various other warnings I wasn't sure what to do with.

comment:8 Changed 14 months ago by vadz

  • Status changed from infoneeded_new to new

First of all, thanks for your fixes!

Some remarks about the questions above (sadly, not really answers):

  • We probably need to just replace "@since" with "Available since wxWidgets x.y.z". It's a pity because it's less greppable than "@since", for example, but I don't see what else can we do.
  • The missing images must be added, there is no way around it...
  • interface/wx/stc/stc.h is generated by src/stc/gen_iface.py since r72787. So it's this script that should probably be modified to escape backslashes and other hash signs.
  • I've fixed those by just duplicating the documentation.

comment:9 Changed 14 months ago by VZ

(In [74704]) Fix Doxygen warnings due to documenting overloaded functions together.

Apparently we can't make @param statements apply just to some overloads, so
document them separately now.

See #15346.

comment:10 Changed 14 months ago by SJL

(In [74782]) Fix doxygen warnings.

Using @since inside a style or event list causes doxygen warnings, replace with plain text.

See #15346.

comment:11 Changed 14 months ago by SJL

(In [74783]) Fix stc doxygen warnings and regen stc files.

We need to manually escape a few parts of the autogenerated documentation.

See #15346.

comment:12 Changed 13 months ago by VZ

(In [74891]) Fix wrong references to wxImageList description in XRC format docs.

xrc_wximagelist reference didn't exist and resulted in Doxygen errors.

See #15346.

comment:13 Changed 13 months ago by VZ

(In [74892]) Document domain parameter of wxTranslations::GetTranslatedString().

This parameter needs to be documented, if only to avoid a Doxygen warning.

See #15346.

comment:14 Changed 13 months ago by VZ

(In [74893]) Use wxListCtrl screenshots for wxListView as well.

wxListView appears identically to wxListCtrl in report mode and the existing
wxListCtrl screenshots show it exactly in this mode, so it doesn't make much
sense to duplicate them.

This also avoids Doxygen warnings about missing wxListView screenshots for
MSW and OSX.

See #15346.

comment:15 Changed 13 months ago by VZ

(In [74895]) Use generic appearance for wxSimpleHtmlListBox.

It doesn't make much sense to have platform-specific screenshots for this
generic control.

See #15346.

comment:16 Changed 13 months ago by VZ

  • Resolution set to fixed
  • Status changed from new to closed

(In [74896]) Add a few missing appearance screenshots for the manual.

This fixes the last remaining Doxygen warnings.

Closes #15346.

Note: See TracTickets for help on using tickets.