Documenting conceptual functions

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Documenting conceptual functions

Zieg, Mark (KSC-ESC-624)[SGT - ESC]
Hi,

Sorry if this has been documented elsewhere, but it's a hard thing to Google for.

I have a C++ application which exposes a service over an API.  I already use Doxygen to render lovely maintenance documentation for the server application itself.

However, I'd also like to use Doxygen to render structured documentation for the API which my server exposes, and here I'm a little confused.  I don't actually have source code for the API "methods," "parameters" and "return values," because client requests are parsed internally by my server as text -- there are no compiled signatures for Doxygen to process.

I know Doxygen has keywords like @brief, @param and @return to document functions.  Is there something like @function to create a "fake function" that those keywords can then decorate?  I tried using @fn, but got "Warning: documented function was not declared or defined," and no documentation was generated.

(PS, I know I could create a "fake" C++ header file, but I was hoping not to.)

Thanks for your suggestions.

------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documenting conceptual functions

Ron Wilson-4
On Fri, Jul 21, 2017 at 8:17 AM, <[hidden email]> wrote:
Date: Thu, 20 Jul 2017 14:19:29 +0000
From: "Zieg, Mark (KSC-ESC-624)[SGT - ESC]" <[hidden email]>
Subject: [Doxygen-users] Documenting conceptual functions

I know Doxygen has keywords like @brief, @param and @return to document functions.  Is there something like @function to create a "fake function" that those keywords can then decorate?  I tried using @fn, but got "Warning: documented function was not declared or defined," and no documentation was generated.

 That's the only one I've ever found.

@par could be used to created a titled paragraph, but would not generate any kind of index entry.

@xrefitem will create both a titled paragraph and entries on an index page with a specified title. I think this is the closest you can get to what you are asking for.


------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Documenting conceptual functions

Andreas Tscharner
In reply to this post by Zieg, Mark (KSC-ESC-624)[SGT - ESC]
On 20.07.2017 16:19, Zieg, Mark (KSC-ESC-624)[SGT - ESC] wrote:

Hi Mark,

[snip]
> However, I'd also like to use Doxygen to render structured documentation
> for the API which my server exposes, and here I'm a little confused.  I
> don't actually have source code for the API "methods," "parameters" and
> "return values," because client requests are parsed internally by my
> server as text -- there are no compiled signatures for Doxygen to process.

I did not try, so I cannot say if it works or not: Try \fn
http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdfn

Best regards
        Andreas
--
      ("`-''-/").___..--''"`-._
       `o_ o  )   `-.  (     ).`-.__.`)
       (_Y_.)'  ._   )  `._ `. ``-..-'
     _..`--'_..-_/  /--'_.' .'
    (il).-''  (li).'  ((!.-'

Andreas Tscharner   [hidden email]   ICQ-No. 14356454


------------------------------------------------------------------------------
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
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users

signature.asc (227 bytes) Download Attachment
Loading...