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 <awill...@whitemice.org>
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:awill...@whitemice.org> 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
> Doxygen-users@lists.sourceforge.net
> 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
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
