Re: [wx-dev] Doxygen Functions and Macros
Bryan Petty
> On Tue, 11 Mar 2008 01:57:23 -0600 Bryan Petty <br...@ibaku.net> wrote:
>
> BP> Sorry, for making this so long, but reading up more on Doxygen, I've
> BP> discovered that there is a preferred way of specifying functions,
> BP> macros, etc. This is not only so that Doxygen's parser can identify,
> BP> and autolink references easier, but also so that the reference is more
> BP> easily identified in the comments:
> BP>
> BP> * functions: "::wxFunction()"
> BP> * macros: "#wxCHECK_VERSION()"
> BP> * variables and enums: "#wxEnumOrVariable"
> BP> * typedefs: "::wxCoord"
> BP>
> BP> This only really steps on our decision a while ago to remove all "#"
> BP> references, but you can see the clear advantage if you look at the
> BP> RTTI section on the macros page (in doxygen/mainpages/cat_macros.h).
> BP> The macros won't autolink without either "::" or "#", and making it
> BP> the same as functions gets really confusing.
>
> I guess we could live with "#" prefix for the macros (although it would be
> better if it wasn't needed) but do we really need "::" for the functions
> and typedefs? I was under impression that there was (maybe optionally?) a
> way to make Doxygen autolink them without it.
Sorry, looks like I was wrong about this, we can autolink both macros
and functions without "::" or "#", but both need to be specified with
"()" at the end. I'd still recommend that we use "#" for macros and
defines though.
Regards,
Bryan Petty
Bryan Petty
> Sorry, looks like I was wrong about this, we can autolink both macros
> and functions without "::" or "#", but both need to be specified with
> "()" at the end. I'd still recommend that we use "#" for macros and
> defines though.
Actually, I take that back, we do already having a naming convention
for wxUPPERCASE macros, wxCamelCase functions, so that should really
be enough I guess.
Sorry I bothered everyone with this. :)
Regards,
Bryan Petty
Francesco Montorsi
> Hi (Francesco),
>
> I don't recall this subject being covered, but I noticed that you
> broke out the functions and macros into two separate pages. I'm
> confused about how we're organizing and listing these.
>
> I think that it's best if the functions and macros are still grouped
> together on the same page. The page is somewhat long, but I think it
> will be confusing if they are separated since a developer might miss
> pertinent macros while looking at a category on the functions page, or
> vise versa.
honestly I don't think this can be a real trouble: the functions are
divided in categories which do not overlap the macro categories (except
for the debugging one)...
> Splitting up the page has also added the extra work of making sure
> that the descriptions and "see also"-like sections of each of the
> categories is updated on both the functions and macros pages. Take the
> "Debugging" category for example; you now have two copies of the same
> paragraph on separate pages.
Debugging is the only case where this happens and in fact we could
change the two descriptions to better fit the relative pages where
they're placed...
> Another issue is that while you've split these up, there's still
> several categories in the "Functions by Category" page that list
> macros, not functions, and giving these their own category on the
> macros page seems rather pointless.
hmm, actually skimming cat_functions.h I only see:
@li wxBITMAP()
@li wxDROP_ICON()
@li wxICON()
all other seems functions...
>
> Also, are we also going to go ahead and keep those function and macro
> docs documented on the page for the header they're in? I've noticed
> that when I generate the docs, the @wxheader command doesn't seem to
> be working for me. Any class with that command shows as being in the
> file without the "wx/" parent folder still, and the file pages linked
> to from the functions and macros also just show the filename without
> the "wx/" prefix.
true... that's annoying...
> On a related note, I've been playing with briefly with adding the
> global functions and macros to a defined group.
>
> For example, I've gone ahead and committed a "Graphics Device
> Interface" group page outlining just the functions and macros outlined
> on the original page in the LaTeX docs. The page source is at
> "docs/doxygen/modules/gdi.h", and it's referenced just like any other
> page or overview, but contains the full documentation of those
> functions and macros. So the function and macro category pages serve
> as an index as intended, and the modules serve as the category
> subpages -- very similar to the way the LaTeX docs are organized.
>
> Note how wxMakeMetafilePlaceable() is documented on that page despite
> the fact that it's in metafile.h, and not gdicmn.h. I don't see any
> other way to do this than with grouping.
Seems a good way to organize functions & macros!
> This also raises another question. While I like that the function and
> macro categories include a small index of the macros and functions
> with the category before you follow the links to the specific macro or
> function, it would be easier to simply list the individual categories
> since we can add functions and macros to groups using @addtogroup
> without ever touching any of the group, function, or macro pages.
>
> Let me know what you think.
That is, you're proposing to put the category descriptions (now in
cat_functions.h and cat_macros.h) in multiple files under "groups"
folder and then to let Doxygen automatically generate a list of
categories under the new "Modules" tab?
In this way the static listing of macros/functions could be completely
removed by header files under the "docs/doxygen" hierarchy and we should
just put @addtogroup macro in the docs of the functions/macros in the
"interface" hierarchy... right?
I'm fine with it! :)
> Sorry, for making this so long, but reading up more on Doxygen, I've
> discovered that there is a preferred way of specifying functions,
> macros, etc. This is not only so that Doxygen's parser can identify,
> and autolink references easier, but also so that the reference is more
> easily identified in the comments:
>
> * functions: "::wxFunction()"
> * macros: "#wxCHECK_VERSION()"
> * variables and enums: "#wxEnumOrVariable"
> * typedefs: "::wxCoord"
>
> This only really steps on our decision a while ago to remove all "#"
> references, but you can see the clear advantage if you look at the
> RTTI section on the macros page (in doxygen/mainpages/cat_macros.h).
> The macros won't autolink without either "::" or "#", and making it
> the same as functions gets really confusing.
As seen on followups of this thread, it seems you agreed on the
conventions defined in tech0003.txt, right?
Yesterday or some day ago I put there:
- for linking use one of:
=> the @ref command to refer to topic overviews;
=> the () suffix to refer to function members of the same class you're
documenting or to refer to global functions or macros;
=> the classname:: operator to refer to functions of classes different
from the one you're documenting;
=> the :: prefix to refer to global variables (e.g. ::wxEmptyString).
Class names are auto-linked by Doxygen without the need of any
explicit command.
I hope it's ok for everyone as it's the most natural syntax for C++
programmers (it avoids the use of # which everyone seemed to dislike).
Thanks for your help!
Francesco
Robin Dunn
> On 3/12/08, Francesco Montorsi <f18m_cp...@yahoo.it> wrote:
>> wxSTC docs are already in the doxygen form; are you referring to these
>> docs: http://www.yellowbrain.com/stc/index.html ?
>
> Yeah. The Doxygen docs for wxSTC do alright with outlining all the
> functions and a brief description of each of them, but it really needs
> the kind of docs provided by the Yellowbrain docs. The Yellowbrain
> docs have little overviews for groups of functions [1] just like how
> we have overviews for groups of classes. It's much more in depth, and
> I think it could benefit from a conversion to Doxygen on the same
> scale that wxWidgets is by moving from LaTeX to Doxygen, especially
> now that it's no longer a contrib project.
>
> [1] http://www.yellowbrain.com/stc/index.html#subjdex (list of subjects)
>
> I'm not saying this needs to be done now, I'm just looking ahead. It
> would be helpful to get a hold of Jeff Sasmor (who holds the
> copyright) first and maybe either him or Robin would want to do this
> assuming they agree that it would be beneficial to move the docs
> there.
A possibly better, certainly more up to date, process might be to start
from the current Scintilla text and wx-ify it by converting the message
names to wxSTC methods, etc. The yellowbrain docs haven't been updated
in a very long time.
--
Robin Dunn
Software Craftsman
http://wxPython.org Java give you jitters? Relax with wxPython!