Thread: [Doxygen-users] are document generators dead?
Brought to you by:
dimitri
Menu
▾
▴
doxygen-users
|
From: Tom J. <tom...@gm...> - 2014-10-07 05:03:27
|
Are document generators for APIs dead? When I look over the possible options out there, everything seems built about 10 years ago. I don't see anything new coming out of this genre of tools. I find this odd, given that APIs themselves are exploding in popularity. I'm guessing that most new APIs today are REST APIs, and none of the current document generators really address REST? Can someone clue me in as to why there aren't more recently developed tools? Doxygen seems to be the best of them, but even Doxygen seems a bit dated to me. Tom --------------------- 801-822-2241 blog: idratherbewriting.com twitter: tomjohnson |
|
From: Adam T. W. <awi...@wh...> - 2014-10-07 12:04:47
|
On Mon, 2014-10-06 at 22:03 -0700, Tom Johnson wrote: > Are document generators for APIs dead? When I look over the possible > options out there, everything seems built about 10 years ago. I don't > see anything new coming out of this genre of tools. I find this odd, > given that APIs themselves are exploding in popularity. Nothing new is required; this is a solved problem. Solved about 10 years ago. > I'm guessing that most new APIs today are REST APIs, and none of the > current document generators really address REST? ??? REST APIs are 'theoretically' self-documenting. Which is total BS, but the trope REST fanboys hide behind. Underlying any REST API is code - an API written in source code - that needs to be documented. And that can be accomplished with the same tools. > Can someone clue me in as to why there aren't more recently developed > tools? Doxygen seems to be the best of them, but even Doxygen seems a > bit dated to me. Why is it "dated"? Something that works is not obsolete. -- Adam Tauno Williams <mailto:awi...@wh...> GPG D95ED383 Systems Administrator, Python Developer, LPI / NCLA |
|
From: Tom J. <tom...@gm...> - 2014-10-07 16:51:48
|
Thanks for your response. Looking at the document generators as a solved problem seems like a okay argument. If the problem were solved 10 yrs ago, why is there any need for additional development? Well, technology is rapidly changing, so there are always opportunities for enhancements and further development. As I said, of all the document generators I've looked at, Doxygen seems to be the most flexible (covering many languages), the easiest to use (the GUI front-end tool), and has a good-looking output. It also seems the most up to date. I'm mostly frustrated that document generators don't naturally integrate with common tech comm authoring structures such as DITA. DITA is probably the most common XML authoring standard among professional technical writers, but it seems a world apart from document generator tools. I don't see why Doxygen can't incorporate simple HTML files into its output. I also don't understand why the majority of web APIs, many of which are probably coded using platforms that Doxygen can create documentation for, aren't using documentation auto-generated from document generators. Tom --------------------- 801-822-2241 blog: idratherbewriting.com twitter: tomjohnson On Tue, Oct 7, 2014 at 5:04 AM, Adam Tauno Williams <awi...@wh...> wrote: > On Mon, 2014-10-06 at 22:03 -0700, Tom Johnson wrote: > > Are document generators for APIs dead? When I look over the possible > > options out there, everything seems built about 10 years ago. I don't > > see anything new coming out of this genre of tools. I find this odd, > > given that APIs themselves are exploding in popularity. > > Nothing new is required; this is a solved problem. Solved about 10 > years ago. > > > I'm guessing that most new APIs today are REST APIs, and none of the > > current document generators really address REST? > > ??? REST APIs are 'theoretically' self-documenting. Which is total BS, > but the trope REST fanboys hide behind. Underlying any REST API is code > - an API written in source code - that needs to be documented. And that > can be accomplished with the same tools. > > Can someone clue me in as to why there aren't more recently developed > > tools? Doxygen seems to be the best of them, but even Doxygen seems a > > bit dated to me. > > Why is it "dated"? Something that works is not obsolete. > > -- > Adam Tauno Williams <mailto:awi...@wh...> GPG D95ED383 > Systems Administrator, Python Developer, LPI / NCLA > > > > ------------------------------------------------------------------------------ > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk > _______________________________________________ > Doxygen-users mailing list > Dox...@li... > https://lists.sourceforge.net/lists/listinfo/doxygen-users > |
|
From: Albert <alb...@gm...> - 2014-10-07 17:39:54
|
Tom, You are talking about DITA, what kind of tools for converting DITA are you using / thinking about? Are they able to import e.g. the HTML as generated by doxygen or the XML that can be generated by doxygen? Albert On Tue, Oct 7, 2014 at 6:21 PM, Tom Johnson <tom...@gm...> wrote: > Thanks for your response. Looking at the document generators as a solved > problem seems like a okay argument. If the problem were solved 10 yrs ago, > why is there any need for additional development? > > Well, technology is rapidly changing, so there are always opportunities > for enhancements and further development. As I said, of all the document > generators I've looked at, Doxygen seems to be the most flexible (covering > many languages), the easiest to use (the GUI front-end tool), and has a > good-looking output. It also seems the most up to date. > > I'm mostly frustrated that document generators don't naturally integrate > with common tech comm authoring structures such as DITA. DITA is probably > the most common XML authoring standard among professional technical > writers, but it seems a world apart from document generator tools. I don't > see why Doxygen can't incorporate simple HTML files into its output. > > I also don't understand why the majority of web APIs, many of which are > probably coded using platforms that Doxygen can create documentation for, > aren't using documentation auto-generated from document generators. > > Tom > > > --------------------- > 801-822-2241 > blog: idratherbewriting.com > twitter: tomjohnson > > On Tue, Oct 7, 2014 at 5:04 AM, Adam Tauno Williams < > awi...@wh...> wrote: > >> On Mon, 2014-10-06 at 22:03 -0700, Tom Johnson wrote: >> > Are document generators for APIs dead? When I look over the possible >> > options out there, everything seems built about 10 years ago. I don't >> > see anything new coming out of this genre of tools. I find this odd, >> > given that APIs themselves are exploding in popularity. >> >> Nothing new is required; this is a solved problem. Solved about 10 >> years ago. >> >> > I'm guessing that most new APIs today are REST APIs, and none of the >> > current document generators really address REST? >> >> ??? REST APIs are 'theoretically' self-documenting. Which is total BS, >> but the trope REST fanboys hide behind. Underlying any REST API is code >> - an API written in source code - that needs to be documented. And that >> can be accomplished with the same tools. >> > Can someone clue me in as to why there aren't more recently developed >> > tools? Doxygen seems to be the best of them, but even Doxygen seems a >> > bit dated to me. >> >> Why is it "dated"? Something that works is not obsolete. >> >> -- >> Adam Tauno Williams <mailto:awi...@wh...> GPG D95ED383 >> Systems Administrator, Python Developer, LPI / NCLA >> >> >> >> ------------------------------------------------------------------------------ >> Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer >> Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports >> Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper >> Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer >> >> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk >> _______________________________________________ >> Doxygen-users mailing list >> Dox...@li... >> https://lists.sourceforge.net/lists/listinfo/doxygen-users >> > > > > ------------------------------------------------------------------------------ > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk > _______________________________________________ > Doxygen-users mailing list > Dox...@li... > https://lists.sourceforge.net/lists/listinfo/doxygen-users > > |
|
From: Tom J. <tom...@gm...> - 2014-10-07 17:57:36
|
I have been exploring two models with DITA. The first model is to import source comments directly into DITA (thus not using Doxygen at all). There are some DITA plugins that work for Java and C++, but nothing for C#. As far as I can tell, the plugins work okay. I haven't explored them too deeply other than to verify that the Java one (from Docfacto) appears to work, though it may need some cleanup. (Part of the difficulty in assessing how it works is that some sections or table rows that are blank may be due to poorly formatted source doc rather than the plugin.) The second model is to take the HTML produced from DITA and incorporate it into Doxygen's output. I couldn't get this to work, though. Ideally, it would be cool if I could export DITA into markdown, but there isn't a transform built for that at the moment. Also, although you can convert HTML into DITA, it would probably need to be a custom-built transform. The default HTML to DITA conversion tools may not auto-process Doxygen's output unless you first do some special things to your HTML. I did send the Docbook output from Doxygen to a company called STILO that specializes in XML conversions, and asked if they could convert it to DITA (because there should be some exchange between Docbook and DITA and vice versa). However, they are slow in getting back to me, and so I don't have an answer there. My guess is that it will be a custom project requiring a lot of time and money. The more I research API documentation, the more fascinating I find it. There are some real challenges here, a lot of innovation and variety, and a strong need for improvement. Tom --------------------- 801-822-2241 blog: idratherbewriting.com twitter: tomjohnson On Tue, Oct 7, 2014 at 10:39 AM, Albert <alb...@gm...> wrote: > Tom, > > You are talking about DITA, what kind of tools for converting DITA are you > using / thinking about? Are they able to import e.g. the HTML as generated > by doxygen or the XML that can be generated by doxygen? > > Albert > > On Tue, Oct 7, 2014 at 6:21 PM, Tom Johnson <tom...@gm...> > wrote: > >> Thanks for your response. Looking at the document generators as a solved >> problem seems like a okay argument. If the problem were solved 10 yrs ago, >> why is there any need for additional development? >> >> Well, technology is rapidly changing, so there are always opportunities >> for enhancements and further development. As I said, of all the document >> generators I've looked at, Doxygen seems to be the most flexible (covering >> many languages), the easiest to use (the GUI front-end tool), and has a >> good-looking output. It also seems the most up to date. >> >> I'm mostly frustrated that document generators don't naturally integrate >> with common tech comm authoring structures such as DITA. DITA is probably >> the most common XML authoring standard among professional technical >> writers, but it seems a world apart from document generator tools. I don't >> see why Doxygen can't incorporate simple HTML files into its output. >> >> I also don't understand why the majority of web APIs, many of which are >> probably coded using platforms that Doxygen can create documentation for, >> aren't using documentation auto-generated from document generators. >> >> Tom >> >> >> --------------------- >> 801-822-2241 >> blog: idratherbewriting.com >> twitter: tomjohnson >> >> On Tue, Oct 7, 2014 at 5:04 AM, Adam Tauno Williams < >> awi...@wh...> wrote: >> >>> On Mon, 2014-10-06 at 22:03 -0700, Tom Johnson wrote: >>> > Are document generators for APIs dead? When I look over the possible >>> > options out there, everything seems built about 10 years ago. I don't >>> > see anything new coming out of this genre of tools. I find this odd, >>> > given that APIs themselves are exploding in popularity. >>> >>> Nothing new is required; this is a solved problem. Solved about 10 >>> years ago. >>> >>> > I'm guessing that most new APIs today are REST APIs, and none of the >>> > current document generators really address REST? >>> >>> ??? REST APIs are 'theoretically' self-documenting. Which is total BS, >>> but the trope REST fanboys hide behind. Underlying any REST API is code >>> - an API written in source code - that needs to be documented. And that >>> can be accomplished with the same tools. >>> > Can someone clue me in as to why there aren't more recently developed >>> > tools? Doxygen seems to be the best of them, but even Doxygen seems a >>> > bit dated to me. >>> >>> Why is it "dated"? Something that works is not obsolete. >>> >>> -- >>> Adam Tauno Williams <mailto:awi...@wh...> GPG D95ED383 >>> Systems Administrator, Python Developer, LPI / NCLA >>> >>> >>> >>> ------------------------------------------------------------------------------ >>> Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer >>> Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports >>> Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper >>> Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer >>> >>> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk >>> _______________________________________________ >>> Doxygen-users mailing list >>> Dox...@li... >>> https://lists.sourceforge.net/lists/listinfo/doxygen-users >>> >> >> >> >> ------------------------------------------------------------------------------ >> Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer >> Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports >> Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper >> Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer >> >> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk >> _______________________________________________ >> Doxygen-users mailing list >> Dox...@li... >> https://lists.sourceforge.net/lists/listinfo/doxygen-users >> >> > |
|
From: Arthur S. <asc...@at...> - 2014-10-07 18:33:14
|
search = ∑<sub>k = 2 ·· n</sub>
 <sub>n</sub><b>C</b><sub>k<sub>
Causes warnings
I'm trying to generate a mathematical statement (sum(k = 2 .. n) immediately
followed by the combinatoric statement, nCk and get doxygen warnings. The
HTML output looks ok in a browser. Is there any way of suppressing the
warnings?
All of the messages are bogus and all are the result of:
* <li>If |<b>P</b>| = 1 is unsuccessful, then try each combination of
positions
* attempting to find a solution. If k = the size of the |<b>P</b>|
then
* the maximum number of searches to find a partition is
* search = ∑<sub>k = 2 ·· n</sub>
*  <sub>n</sub><b>C</b><sub>k<sub>.
* </li>
===== warnings =====
C:/home/skidmarks/Projects/MPHASH/mphash/StringPartition.h:448: warning: end
of comment block while expecting command </subscript>
C:/home/skidmarks/Projects/MPHASH/mphash/StringPartition.h:448: warning: end
of comment block while expecting command </subscript>
C:/home/skidmarks/Projects/MPHASH/mphash/StringPartition.h:868: warning: end
of comment block while expecting command </subscript>
C:/home/skidmarks/Projects/MPHASH/mphash/StringPartition.h:868: warning: end
of comment block while expecting command </subscript>
error: perl: non supported HTML-entity found: ·
error: perl: non supported HTML-entity found: ·
error: perl: non supported HTML-entity found:  
|
|
From: Dimitri v. H. <do...@gm...> - 2014-10-07 18:57:14
|
Hi Arthur,
For such complex formulas it is much better to use LaTeX notation, i.e.
/** The maximum number of searches to find a partition is
* \c search = \f$\sum\limits_{2..n}^k{n \choose k}\f$
*/
If you don't have LaTeX installed you could enable MathJax to render the
formula at the client side:
USE_MATHJAX = YES
Regards,
Dimitri
On 07 Oct 2014, at 20:16 , Arthur Schwarz <asc...@at...> wrote:
> search = ∑<sub>k = 2 ·· n</sub>
>  <sub>n</sub><b>C</b><sub>k<sub>
>
> Causes warnings
> I'm trying to generate a mathematical statement (sum(k = 2 .. n) immediately
> followed by the combinatoric statement, nCk and get doxygen warnings. The
> HTML output looks ok in a browser. Is there any way of suppressing the
> warnings?
>
> All of the messages are bogus and all are the result of:
>
> * <li>If |<b>P</b>| = 1 is unsuccessful, then try each combination of
> positions
> * attempting to find a solution. If k = the size of the |<b>P</b>|
> then
> * the maximum number of searches to find a partition is
> * search = ∑<sub>k = 2 ·· n</sub>
> *  <sub>n</sub><b>C</b><sub>k<sub>.
> * </li>
>
> ===== warnings =====
> C:/home/skidmarks/Projects/MPHASH/mphash/StringPartition.h:448: warning: end
> of comment block while expecting command </subscript>
> C:/home/skidmarks/Projects/MPHASH/mphash/StringPartition.h:448: warning: end
> of comment block while expecting command </subscript>
> C:/home/skidmarks/Projects/MPHASH/mphash/StringPartition.h:868: warning: end
> of comment block while expecting command </subscript>
> C:/home/skidmarks/Projects/MPHASH/mphash/StringPartition.h:868: warning: end
> of comment block while expecting command </subscript>
> error: perl: non supported HTML-entity found: ·
> error: perl: non supported HTML-entity found: ·
> error: perl: non supported HTML-entity found:  
>
>
> ------------------------------------------------------------------------------
> Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer
> Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports
> Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper
> Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer
> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
|
|
From: Robert H. <he...@de...> - 2014-10-07 12:41:29
|
At Mon, 6 Oct 2014 22:03:20 -0700 Tom Johnson <tom...@gm...> wrote: > > > > Are document generators for APIs dead? When I look over the possible > options out there, everything seems built about 10 years ago. I don't see > anything new coming out of this genre of tools. I find this odd, given that > APIs themselves are exploding in popularity. > > I'm guessing that most new APIs today are REST APIs, and none of the > current document generators really address REST? > > Can someone clue me in as to why there aren't more recently developed > tools? Doxygen seems to be the best of them, but even Doxygen seems a bit > dated to me. Define 'dated'... What are you expecting? OTOH: "If it ain't broke, don't fix it."... > > Tom > --------------------- > 801-822-2241 > blog: idratherbewriting.com > twitter: tomjohnson > > MIME-Version: 1.0 > > ------------------------------------------------------------------------------ > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk > MIME-Version: 1.0 > > _______________________________________________ > Doxygen-users mailing list > Dox...@li... > https://lists.sourceforge.net/lists/listinfo/doxygen-users > > -- Robert Heller -- 978-544-6933 Deepwoods Software -- Custom Software Services http://www.deepsoft.com/ -- Linux Administration Services he...@de... -- Webhosting Services |
|
From: Paul J. <pau...@gm...> - 2014-10-07 14:12:26
|
Doxygen is excellent and especially useful for C/C++ or "like-minded" languages. A few years ago I switched to developing most of my code in Python and while Doxygen can handle this, it is not ideal, in that case I turn to Sphinx which is ideal for Python but also useful for general purpose API documentation: http://sphinx-doc.org/ It is based on docutils and reStructuredText, while I'm not the biggest fan of reStructuredText the Sphinx additions make it very usable. If you are looking for some REST API documentation tools I'd point you to Swagger: https://helloreverb.com/developers/swagger Paul Joireman On Tue, Oct 7, 2014 at 7:21 AM, Robert Heller <he...@de...> wrote: > At Mon, 6 Oct 2014 22:03:20 -0700 Tom Johnson <tom...@gm...> > wrote: > > > > > > > > > Are document generators for APIs dead? When I look over the possible > > options out there, everything seems built about 10 years ago. I don't see > > anything new coming out of this genre of tools. I find this odd, given > that > > APIs themselves are exploding in popularity. > > > > I'm guessing that most new APIs today are REST APIs, and none of the > > current document generators really address REST? > > > > Can someone clue me in as to why there aren't more recently developed > > tools? Doxygen seems to be the best of them, but even Doxygen seems a bit > > dated to me. > > Define 'dated'... What are you expecting? > > OTOH: "If it ain't broke, don't fix it."... > > > > > Tom > > --------------------- > > 801-822-2241 > > blog: idratherbewriting.com > > twitter: tomjohnson > > > > MIME-Version: 1.0 > > > > > ------------------------------------------------------------------------------ > > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > > > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk > > MIME-Version: 1.0 > > > > _______________________________________________ > > Doxygen-users mailing list > > Dox...@li... > > https://lists.sourceforge.net/lists/listinfo/doxygen-users > > > > > > -- > Robert Heller -- 978-544-6933 > Deepwoods Software -- Custom Software Services > http://www.deepsoft.com/ -- Linux Administration Services > he...@de... -- Webhosting Services > > > > ------------------------------------------------------------------------------ > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk > _______________________________________________ > Doxygen-users mailing list > Dox...@li... > https://lists.sourceforge.net/lists/listinfo/doxygen-users > -- Paul W. Joireman pau...@gm... ---------------------------------------------------------------- 'Am I not destroying my enemies when I make friends of them? ." -- Abraham Lincoln 1809-1865 |
|
From: Albert <alb...@gm...> - 2014-10-07 18:05:47
|
Tom, As far as I know DITA is a methodology (Darwin Information Typing Architecture) and not a tool. The tools I'm aware of are Serna and DITA-OT. For the latter wikipedia (http://en.wikipedia.org/wiki/DITA_Open_Toolkit) states: It includes a tool for migrating HTML <http://en.wikipedia.org/wiki/HTML> to DITA. Probably this requires that the HTML consists of some "DITA structure" though. Did you have look at this? Albert On Tue, Oct 7, 2014 at 7:57 PM, Tom Johnson <tom...@gm...> wrote: > I have been exploring two models with DITA. The first model is to import > source comments directly into DITA (thus not using Doxygen at all). There > are some DITA plugins that work for Java and C++, but nothing for C#. As > far as I can tell, the plugins work okay. I haven't explored them too > deeply other than to verify that the Java one (from Docfacto) appears to > work, though it may need some cleanup. (Part of the difficulty in assessing > how it works is that some sections or table rows that are blank may be due > to poorly formatted source doc rather than the plugin.) > > The second model is to take the HTML produced from DITA and incorporate it > into Doxygen's output. I couldn't get this to work, though. Ideally, it > would be cool if I could export DITA into markdown, but there isn't a > transform built for that at the moment. Also, although you can convert HTML > into DITA, it would probably need to be a custom-built transform. The > default HTML to DITA conversion tools may not auto-process Doxygen's output > unless you first do some special things to your HTML. > > I did send the Docbook output from Doxygen to a company called STILO that > specializes in XML conversions, and asked if they could convert it to DITA > (because there should be some exchange between Docbook and DITA and vice > versa). However, they are slow in getting back to me, and so I don't have > an answer there. My guess is that it will be a custom project requiring a > lot of time and money. > > The more I research API documentation, the more fascinating I find it. > There are some real challenges here, a lot of innovation and variety, and a > strong need for improvement. > > Tom > > --------------------- > 801-822-2241 > blog: idratherbewriting.com > twitter: tomjohnson > > On Tue, Oct 7, 2014 at 10:39 AM, Albert <alb...@gm...> wrote: > >> Tom, >> >> You are talking about DITA, what kind of tools for converting DITA are >> you using / thinking about? Are they able to import e.g. the HTML as >> generated by doxygen or the XML that can be generated by doxygen? >> >> Albert >> >> On Tue, Oct 7, 2014 at 6:21 PM, Tom Johnson <tom...@gm...> >> wrote: >> >>> Thanks for your response. Looking at the document generators as a solved >>> problem seems like a okay argument. If the problem were solved 10 yrs ago, >>> why is there any need for additional development? >>> >>> Well, technology is rapidly changing, so there are always opportunities >>> for enhancements and further development. As I said, of all the document >>> generators I've looked at, Doxygen seems to be the most flexible (covering >>> many languages), the easiest to use (the GUI front-end tool), and has a >>> good-looking output. It also seems the most up to date. >>> >>> I'm mostly frustrated that document generators don't naturally integrate >>> with common tech comm authoring structures such as DITA. DITA is probably >>> the most common XML authoring standard among professional technical >>> writers, but it seems a world apart from document generator tools. I don't >>> see why Doxygen can't incorporate simple HTML files into its output. >>> >>> I also don't understand why the majority of web APIs, many of which are >>> probably coded using platforms that Doxygen can create documentation for, >>> aren't using documentation auto-generated from document generators. >>> >>> Tom >>> >>> >>> --------------------- >>> 801-822-2241 >>> blog: idratherbewriting.com >>> twitter: tomjohnson >>> >>> On Tue, Oct 7, 2014 at 5:04 AM, Adam Tauno Williams < >>> awi...@wh...> wrote: >>> >>>> On Mon, 2014-10-06 at 22:03 -0700, Tom Johnson wrote: >>>> > Are document generators for APIs dead? When I look over the possible >>>> > options out there, everything seems built about 10 years ago. I don't >>>> > see anything new coming out of this genre of tools. I find this odd, >>>> > given that APIs themselves are exploding in popularity. >>>> >>>> Nothing new is required; this is a solved problem. Solved about 10 >>>> years ago. >>>> >>>> > I'm guessing that most new APIs today are REST APIs, and none of the >>>> > current document generators really address REST? >>>> >>>> ??? REST APIs are 'theoretically' self-documenting. Which is total BS, >>>> but the trope REST fanboys hide behind. Underlying any REST API is code >>>> - an API written in source code - that needs to be documented. And that >>>> can be accomplished with the same tools. >>>> > Can someone clue me in as to why there aren't more recently developed >>>> > tools? Doxygen seems to be the best of them, but even Doxygen seems a >>>> > bit dated to me. >>>> >>>> Why is it "dated"? Something that works is not obsolete. >>>> >>>> -- >>>> Adam Tauno Williams <mailto:awi...@wh...> GPG D95ED383 >>>> Systems Administrator, Python Developer, LPI / NCLA >>>> >>>> >>>> >>>> ------------------------------------------------------------------------------ >>>> Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer >>>> Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports >>>> Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper >>>> Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer >>>> >>>> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk >>>> _______________________________________________ >>>> Doxygen-users mailing list >>>> Dox...@li... >>>> https://lists.sourceforge.net/lists/listinfo/doxygen-users >>>> >>> >>> >>> >>> ------------------------------------------------------------------------------ >>> Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer >>> Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports >>> Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper >>> Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer >>> >>> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk >>> _______________________________________________ >>> Doxygen-users mailing list >>> Dox...@li... >>> https://lists.sourceforge.net/lists/listinfo/doxygen-users >>> >>> >> > |
|
From: Tom J. <tom...@gm...> - 2014-10-07 18:13:42
|
You are correct. DITA is an XML standard, not a tool. I use OxygenXML as an editor to validate my DITA content. I have explored the HTML to DITA transform, and added some notes about using it here ( http://idratherbewriting.com/ditaqrg/#convert_html_to_dita.html), but honestly it's not an easy process. I can guarantee that bulk converting Doxygen's HTML output will require some major tweaking of some kind. --------------------- 801-822-2241 blog: idratherbewriting.com twitter: tomjohnson On Tue, Oct 7, 2014 at 11:05 AM, Albert <alb...@gm...> wrote: > Tom, > > As far as I know DITA is a methodology (Darwin Information Typing > Architecture) and not a tool. The tools I'm aware of are Serna and DITA-OT. > For the latter wikipedia (http://en.wikipedia.org/wiki/DITA_Open_Toolkit) > states: It includes a tool for migrating HTML > <http://en.wikipedia.org/wiki/HTML> to DITA. > Probably this requires that the HTML consists of some "DITA structure" > though. Did you have look at this? > > Albert > > On Tue, Oct 7, 2014 at 7:57 PM, Tom Johnson <tom...@gm...> > wrote: > >> I have been exploring two models with DITA. The first model is to import >> source comments directly into DITA (thus not using Doxygen at all). There >> are some DITA plugins that work for Java and C++, but nothing for C#. As >> far as I can tell, the plugins work okay. I haven't explored them too >> deeply other than to verify that the Java one (from Docfacto) appears to >> work, though it may need some cleanup. (Part of the difficulty in assessing >> how it works is that some sections or table rows that are blank may be due >> to poorly formatted source doc rather than the plugin.) >> >> The second model is to take the HTML produced from DITA and incorporate >> it into Doxygen's output. I couldn't get this to work, though. Ideally, it >> would be cool if I could export DITA into markdown, but there isn't a >> transform built for that at the moment. Also, although you can convert HTML >> into DITA, it would probably need to be a custom-built transform. The >> default HTML to DITA conversion tools may not auto-process Doxygen's output >> unless you first do some special things to your HTML. >> >> I did send the Docbook output from Doxygen to a company called STILO that >> specializes in XML conversions, and asked if they could convert it to DITA >> (because there should be some exchange between Docbook and DITA and vice >> versa). However, they are slow in getting back to me, and so I don't have >> an answer there. My guess is that it will be a custom project requiring a >> lot of time and money. >> >> The more I research API documentation, the more fascinating I find it. >> There are some real challenges here, a lot of innovation and variety, and a >> strong need for improvement. >> >> Tom >> >> --------------------- >> 801-822-2241 >> blog: idratherbewriting.com >> twitter: tomjohnson >> >> On Tue, Oct 7, 2014 at 10:39 AM, Albert <alb...@gm...> wrote: >> >>> Tom, >>> >>> You are talking about DITA, what kind of tools for converting DITA are >>> you using / thinking about? Are they able to import e.g. the HTML as >>> generated by doxygen or the XML that can be generated by doxygen? >>> >>> Albert >>> >>> On Tue, Oct 7, 2014 at 6:21 PM, Tom Johnson <tom...@gm...> >>> wrote: >>> >>>> Thanks for your response. Looking at the document generators as a >>>> solved problem seems like a okay argument. If the problem were solved 10 >>>> yrs ago, why is there any need for additional development? >>>> >>>> Well, technology is rapidly changing, so there are always opportunities >>>> for enhancements and further development. As I said, of all the document >>>> generators I've looked at, Doxygen seems to be the most flexible (covering >>>> many languages), the easiest to use (the GUI front-end tool), and has a >>>> good-looking output. It also seems the most up to date. >>>> >>>> I'm mostly frustrated that document generators don't naturally >>>> integrate with common tech comm authoring structures such as DITA. DITA is >>>> probably the most common XML authoring standard among professional >>>> technical writers, but it seems a world apart from document generator >>>> tools. I don't see why Doxygen can't incorporate simple HTML files into its >>>> output. >>>> >>>> I also don't understand why the majority of web APIs, many of which are >>>> probably coded using platforms that Doxygen can create documentation for, >>>> aren't using documentation auto-generated from document generators. >>>> >>>> Tom >>>> >>>> >>>> --------------------- >>>> 801-822-2241 >>>> blog: idratherbewriting.com >>>> twitter: tomjohnson >>>> >>>> On Tue, Oct 7, 2014 at 5:04 AM, Adam Tauno Williams < >>>> awi...@wh...> wrote: >>>> >>>>> On Mon, 2014-10-06 at 22:03 -0700, Tom Johnson wrote: >>>>> > Are document generators for APIs dead? When I look over the possible >>>>> > options out there, everything seems built about 10 years ago. I don't >>>>> > see anything new coming out of this genre of tools. I find this odd, >>>>> > given that APIs themselves are exploding in popularity. >>>>> >>>>> Nothing new is required; this is a solved problem. Solved about 10 >>>>> years ago. >>>>> >>>>> > I'm guessing that most new APIs today are REST APIs, and none of the >>>>> > current document generators really address REST? >>>>> >>>>> ??? REST APIs are 'theoretically' self-documenting. Which is total >>>>> BS, >>>>> but the trope REST fanboys hide behind. Underlying any REST API is >>>>> code >>>>> - an API written in source code - that needs to be documented. And >>>>> that >>>>> can be accomplished with the same tools. >>>>> > Can someone clue me in as to why there aren't more recently developed >>>>> > tools? Doxygen seems to be the best of them, but even Doxygen seems a >>>>> > bit dated to me. >>>>> >>>>> Why is it "dated"? Something that works is not obsolete. >>>>> >>>>> -- >>>>> Adam Tauno Williams <mailto:awi...@wh...> GPG D95ED383 >>>>> Systems Administrator, Python Developer, LPI / NCLA >>>>> >>>>> >>>>> >>>>> ------------------------------------------------------------------------------ >>>>> Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer >>>>> Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS >>>>> Reports >>>>> Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper >>>>> Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer >>>>> >>>>> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk >>>>> _______________________________________________ >>>>> Doxygen-users mailing list >>>>> Dox...@li... >>>>> https://lists.sourceforge.net/lists/listinfo/doxygen-users >>>>> >>>> >>>> >>>> >>>> ------------------------------------------------------------------------------ >>>> Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer >>>> Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports >>>> Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper >>>> Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer >>>> >>>> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk >>>> _______________________________________________ >>>> Doxygen-users mailing list >>>> Dox...@li... >>>> https://lists.sourceforge.net/lists/listinfo/doxygen-users >>>> >>>> >>> >> > |
|
From: Dimitri v. H. <do...@gm...> - 2014-10-07 19:05:14
|
Hi Tom, There was a patch made a couple of years ago to add DITA support to doxygen, it can still be found here: http://sourceforge.net/p/doxygen/mailman/message/27204707/ I haven't integrated it, because I saw very little interest in it so far. Maybe you want to help to get it up to date again? Regards, Dimitri On 07 Oct 2014, at 20:13 , Tom Johnson <tom...@gm...> wrote: > You are correct. DITA is an XML standard, not a tool. I use OxygenXML as an editor to validate my DITA content. I have explored the HTML to DITA transform, and added some notes about using it here (http://idratherbewriting.com/ditaqrg/#convert_html_to_dita.html), but honestly it's not an easy process. I can guarantee that bulk converting Doxygen's HTML output will require some major tweaking of some kind. > > --------------------- > 801-822-2241 > blog: idratherbewriting.com > twitter: tomjohnson > > On Tue, Oct 7, 2014 at 11:05 AM, Albert <alb...@gm...> wrote: > Tom, > > As far as I know DITA is a methodology (Darwin Information Typing Architecture) and not a tool. The tools I'm aware of are Serna and DITA-OT. For the latter wikipedia (http://en.wikipedia.org/wiki/DITA_Open_Toolkit) states: It includes a tool for migrating HTML to DITA. > Probably this requires that the HTML consists of some "DITA structure" though. Did you have look at this? > > Albert > > On Tue, Oct 7, 2014 at 7:57 PM, Tom Johnson <tom...@gm...> wrote: > I have been exploring two models with DITA. The first model is to import source comments directly into DITA (thus not using Doxygen at all). There are some DITA plugins that work for Java and C++, but nothing for C#. As far as I can tell, the plugins work okay. I haven't explored them too deeply other than to verify that the Java one (from Docfacto) appears to work, though it may need some cleanup. (Part of the difficulty in assessing how it works is that some sections or table rows that are blank may be due to poorly formatted source doc rather than the plugin.) > > The second model is to take the HTML produced from DITA and incorporate it into Doxygen's output. I couldn't get this to work, though. Ideally, it would be cool if I could export DITA into markdown, but there isn't a transform built for that at the moment. Also, although you can convert HTML into DITA, it would probably need to be a custom-built transform. The default HTML to DITA conversion tools may not auto-process Doxygen's output unless you first do some special things to your HTML. > > I did send the Docbook output from Doxygen to a company called STILO that specializes in XML conversions, and asked if they could convert it to DITA (because there should be some exchange between Docbook and DITA and vice versa). However, they are slow in getting back to me, and so I don't have an answer there. My guess is that it will be a custom project requiring a lot of time and money. > > The more I research API documentation, the more fascinating I find it. There are some real challenges here, a lot of innovation and variety, and a strong need for improvement. > > Tom > > --------------------- > 801-822-2241 > blog: idratherbewriting.com > twitter: tomjohnson > > On Tue, Oct 7, 2014 at 10:39 AM, Albert <alb...@gm...> wrote: > Tom, > > You are talking about DITA, what kind of tools for converting DITA are you using / thinking about? Are they able to import e.g. the HTML as generated by doxygen or the XML that can be generated by doxygen? > > Albert > > On Tue, Oct 7, 2014 at 6:21 PM, Tom Johnson <tom...@gm...> wrote: > Thanks for your response. Looking at the document generators as a solved problem seems like a okay argument. If the problem were solved 10 yrs ago, why is there any need for additional development? > > Well, technology is rapidly changing, so there are always opportunities for enhancements and further development. As I said, of all the document generators I've looked at, Doxygen seems to be the most flexible (covering many languages), the easiest to use (the GUI front-end tool), and has a good-looking output. It also seems the most up to date. > > I'm mostly frustrated that document generators don't naturally integrate with common tech comm authoring structures such as DITA. DITA is probably the most common XML authoring standard among professional technical writers, but it seems a world apart from document generator tools. I don't see why Doxygen can't incorporate simple HTML files into its output. > > I also don't understand why the majority of web APIs, many of which are probably coded using platforms that Doxygen can create documentation for, aren't using documentation auto-generated from document generators. > > Tom > > > --------------------- > 801-822-2241 > blog: idratherbewriting.com > twitter: tomjohnson > > On Tue, Oct 7, 2014 at 5:04 AM, Adam Tauno Williams <awi...@wh...> wrote: > On Mon, 2014-10-06 at 22:03 -0700, Tom Johnson wrote: > > Are document generators for APIs dead? When I look over the possible > > options out there, everything seems built about 10 years ago. I don't > > see anything new coming out of this genre of tools. I find this odd, > > given that APIs themselves are exploding in popularity. > > Nothing new is required; this is a solved problem. Solved about 10 > years ago. > > > I'm guessing that most new APIs today are REST APIs, and none of the > > current document generators really address REST? > > ??? REST APIs are 'theoretically' self-documenting. Which is total BS, > but the trope REST fanboys hide behind. Underlying any REST API is code > - an API written in source code - that needs to be documented. And that > can be accomplished with the same tools. > > Can someone clue me in as to why there aren't more recently developed > > tools? Doxygen seems to be the best of them, but even Doxygen seems a > > bit dated to me. > > Why is it "dated"? Something that works is not obsolete. > > -- > Adam Tauno Williams <mailto:awi...@wh...> GPG D95ED383 > Systems Administrator, Python Developer, LPI / NCLA > > > ------------------------------------------------------------------------------ > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk > _______________________________________________ > Doxygen-users mailing list > Dox...@li... > https://lists.sourceforge.net/lists/listinfo/doxygen-users > > > ------------------------------------------------------------------------------ > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk > _______________________________________________ > Doxygen-users mailing list > Dox...@li... > https://lists.sourceforge.net/lists/listinfo/doxygen-users > > > > > > ------------------------------------------------------------------------------ > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk_______________________________________________ > Doxygen-users mailing list > Dox...@li... > https://lists.sourceforge.net/lists/listinfo/doxygen-users |
|
From: Tom J. <tom...@gm...> - 2014-10-07 19:17:41
|
Awesome. It's good to learn there was a patch made. I found a corresponding thread about the DITA output from Doxygen here: https://www.linkedin.com/groups/How-can-I-generate-DITA-3709151.S.5890104139333001219 I will have to explore this in the coming days/weeks to evaluate how it all works. Overall, it's encouraging. As I understand it, the patch works with version 1.7.4 of Doxygen, and there would need to be some updates made to the patch to make it work with the latest version of Doxygen. I would really be interested in helping move this forward. I'm not a developer, so at most I could perhaps have my company hire dev resources to make the update. However, I know there's a rift between the DITA world and the API doc world. This seems to be the most promising bridge. Tom --------------------- 801-822-2241 blog: idratherbewriting.com twitter: tomjohnson On Tue, Oct 7, 2014 at 12:05 PM, Dimitri van Heesch <do...@gm...> wrote: > Hi Tom, > > There was a patch made a couple of years ago to add DITA support to > doxygen, it can still be found here: > http://sourceforge.net/p/doxygen/mailman/message/27204707/ > > I haven't integrated it, because I saw very little interest in it so far. > Maybe you want to help to get it up to date again? > > Regards, > Dimitri > > On 07 Oct 2014, at 20:13 , Tom Johnson <tom...@gm...> wrote: > > > You are correct. DITA is an XML standard, not a tool. I use OxygenXML as > an editor to validate my DITA content. I have explored the HTML to DITA > transform, and added some notes about using it here ( > http://idratherbewriting.com/ditaqrg/#convert_html_to_dita.html), but > honestly it's not an easy process. I can guarantee that bulk converting > Doxygen's HTML output will require some major tweaking of some kind. > > > > --------------------- > > 801-822-2241 > > blog: idratherbewriting.com > > twitter: tomjohnson > > > > On Tue, Oct 7, 2014 at 11:05 AM, Albert <alb...@gm...> wrote: > > Tom, > > > > As far as I know DITA is a methodology (Darwin Information Typing > Architecture) and not a tool. The tools I'm aware of are Serna and DITA-OT. > For the latter wikipedia (http://en.wikipedia.org/wiki/DITA_Open_Toolkit) > states: It includes a tool for migrating HTML to DITA. > > Probably this requires that the HTML consists of some "DITA structure" > though. Did you have look at this? > > > > Albert > > > > On Tue, Oct 7, 2014 at 7:57 PM, Tom Johnson <tom...@gm...> > wrote: > > I have been exploring two models with DITA. The first model is to import > source comments directly into DITA (thus not using Doxygen at all). There > are some DITA plugins that work for Java and C++, but nothing for C#. As > far as I can tell, the plugins work okay. I haven't explored them too > deeply other than to verify that the Java one (from Docfacto) appears to > work, though it may need some cleanup. (Part of the difficulty in assessing > how it works is that some sections or table rows that are blank may be due > to poorly formatted source doc rather than the plugin.) > > > > The second model is to take the HTML produced from DITA and incorporate > it into Doxygen's output. I couldn't get this to work, though. Ideally, it > would be cool if I could export DITA into markdown, but there isn't a > transform built for that at the moment. Also, although you can convert HTML > into DITA, it would probably need to be a custom-built transform. The > default HTML to DITA conversion tools may not auto-process Doxygen's output > unless you first do some special things to your HTML. > > > > I did send the Docbook output from Doxygen to a company called STILO > that specializes in XML conversions, and asked if they could convert it to > DITA (because there should be some exchange between Docbook and DITA and > vice versa). However, they are slow in getting back to me, and so I don't > have an answer there. My guess is that it will be a custom project > requiring a lot of time and money. > > > > The more I research API documentation, the more fascinating I find it. > There are some real challenges here, a lot of innovation and variety, and a > strong need for improvement. > > > > Tom > > > > --------------------- > > 801-822-2241 > > blog: idratherbewriting.com > > twitter: tomjohnson > > > > On Tue, Oct 7, 2014 at 10:39 AM, Albert <alb...@gm...> wrote: > > Tom, > > > > You are talking about DITA, what kind of tools for converting DITA are > you using / thinking about? Are they able to import e.g. the HTML as > generated by doxygen or the XML that can be generated by doxygen? > > > > Albert > > > > On Tue, Oct 7, 2014 at 6:21 PM, Tom Johnson <tom...@gm...> > wrote: > > Thanks for your response. Looking at the document generators as a solved > problem seems like a okay argument. If the problem were solved 10 yrs ago, > why is there any need for additional development? > > > > Well, technology is rapidly changing, so there are always opportunities > for enhancements and further development. As I said, of all the document > generators I've looked at, Doxygen seems to be the most flexible (covering > many languages), the easiest to use (the GUI front-end tool), and has a > good-looking output. It also seems the most up to date. > > > > I'm mostly frustrated that document generators don't naturally integrate > with common tech comm authoring structures such as DITA. DITA is probably > the most common XML authoring standard among professional technical > writers, but it seems a world apart from document generator tools. I don't > see why Doxygen can't incorporate simple HTML files into its output. > > > > I also don't understand why the majority of web APIs, many of which are > probably coded using platforms that Doxygen can create documentation for, > aren't using documentation auto-generated from document generators. > > > > Tom > > > > > > --------------------- > > 801-822-2241 > > blog: idratherbewriting.com > > twitter: tomjohnson > > > > On Tue, Oct 7, 2014 at 5:04 AM, Adam Tauno Williams < > awi...@wh...> wrote: > > On Mon, 2014-10-06 at 22:03 -0700, Tom Johnson wrote: > > > Are document generators for APIs dead? When I look over the possible > > > options out there, everything seems built about 10 years ago. I don't > > > see anything new coming out of this genre of tools. I find this odd, > > > given that APIs themselves are exploding in popularity. > > > > Nothing new is required; this is a solved problem. Solved about 10 > > years ago. > > > > > I'm guessing that most new APIs today are REST APIs, and none of the > > > current document generators really address REST? > > > > ??? REST APIs are 'theoretically' self-documenting. Which is total BS, > > but the trope REST fanboys hide behind. Underlying any REST API is code > > - an API written in source code - that needs to be documented. And that > > can be accomplished with the same tools. > > > Can someone clue me in as to why there aren't more recently developed > > > tools? Doxygen seems to be the best of them, but even Doxygen seems a > > > bit dated to me. > > > > Why is it "dated"? Something that works is not obsolete. > > > > -- > > Adam Tauno Williams <mailto:awi...@wh...> GPG D95ED383 > > Systems Administrator, Python Developer, LPI / NCLA > > > > > > > ------------------------------------------------------------------------------ > > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > > > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk > > _______________________________________________ > > Doxygen-users mailing list > > Dox...@li... > > https://lists.sourceforge.net/lists/listinfo/doxygen-users > > > > > > > ------------------------------------------------------------------------------ > > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > > > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk > > _______________________________________________ > > Doxygen-users mailing list > > Dox...@li... > > https://lists.sourceforge.net/lists/listinfo/doxygen-users > > > > > > > > > > > > > ------------------------------------------------------------------------------ > > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer > > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports > > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper > > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer > > > http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk_______________________________________________ > > Doxygen-users mailing list > > Dox...@li... > > https://lists.sourceforge.net/lists/listinfo/doxygen-users > > |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X