The Confluence 3.0 macro browser does not handle user macros yet. We will consider this for a future release.

If you would like to know how we select features for releases, please read:
http://confluence.atlassian.com/display/DEV/Implementation+of+New+Features+and+Improvements

We are working on a new feature that may address this, allowing you to browse macros and view the relevant documentation and preview the results of the macro. We hope to release this in summer 2009.

Is combining the User Macros into a User Macro Plugin a possible solution to this issue? From my understanding a User Macro Plugin is intended to allow packaging of user macros for distribution, but it also appears to allow the creation of *.vm scripts to create the content for the notation guide.

http://confluence.atlassian.com/display/DOC/User+Macro+Plugins

The only drawback appears to be that the User Macros won't appear in the User Macro section of the admin and thus are not directly editable.

This would be very helpful. It would also be great to have more examples available about how to create useful macros of this type, how to have them use existing macros, etc.

What I'm trying to do is recreate a lot of the macros that Wikipedia has (in dispute, outdated page, stub, etc.).

I'd love to see user macros in the notation guide, however there are many cases where you'd want to keep them hidden (eg. if they are just there as little hacks to do certain things in one or two places and not intended for general consumption).

We've added a lot of custom user macros and so far we haven't found a good way to let our users know about them. Unless I'm mistaken only administrators can even see the list of macros which is the only place right now where they are described.

One possibility would be to allow each macro to register an optional 'home page' in the Wiki. This page could then provide all the documentation necessary to use the macro. There would then need to be a master page that listed all of the macros with links to their doc.

Please also see comment http://confluence.atlassian.com/display/DOC/User+Macros?focusedCommentId=135300#comment-135300

My suggestion is something like

#/**
#* Does *something* useful.
#* @notation \{something-useful\}_Content_\{something-useful\}
#* @notation \{something-useful:_Some Title_\}_Content_\{something-useful\}
#* @param 0 some useful title
#* @param 1 some useful option
#* @param body some useful content
#*/

As alternative their might be appropriate input fields in addition to the macro-source like "comment" and "notation". This alternative might ease to offer a preview button for especially the comment.