#2741 Generating Documentation

jhughes Wed 27 Feb

Added fandoc syntax to my code and having docApi=true in my build file. All the expected apidoc files are are compiled into the pod doc folder. What i've not been able to figure out from the documentation is what's the purpose of these files.

  1. How are the apidoc files accessed/viewed?
  2. Should this option be also generating the html files in the doc directory of the fantom install?
  3. How does one go from fan doc syntax in their code into the html files?

go4 Wed 27 Feb

Do you mean how to generate documents?

Generate all doc:

fan compilerDoc -all

By pod name:

fan compilerDoc util

SlimerDude Wed 27 Feb

what's the purpose of these files.

.apidoc files are machine readable versions of Fantom type documentation. They let you distribute API documentation without the source code.

As go4 noted, HTML documentation may be generated by compilerDoc and yes, this is a rather undocumented feature.

.apidoc files allow other software to read and display Fantom documentation, examples of which are:

  • Explorer desktop file explorer / fandoc viewer
  • Eggbox pod repository

jhughes Wed 27 Feb

So there's an extra step to generate the html files which is what i'm really after that requires the compilerDoc command, easy enough.

What i'm still not sure about is the concept of the .apidoc files and more directly, what is their purpose?

You mention 2 different third party software packages ready to read this type of file for displaying them but then where does it fit in fantom proper? Say I am a fantom developer and I generated .apidoc files and then wanted to review my documentation I just created before I sent them to another fantom developer. Is this what the html files are for as the human readable version of these files?

They let you distribute API documentation without the source code.

Say I distribute these files to that second developer but then what? What would they or I do if I received such files to review them? If it's a machine readable format for distribution, what "machine" is reading these for human consumption?

I guess real world use case for .apidoc is at the core of my question now. HTML generation is human readable and available. apidoc files seem to require additional software to become useful that doesn't (or maybe does?) exist in fantom already.

brian Thu 14 Mar

I guess real world use case for .apidoc is at the core of my question now.

That is an internal format output by compiler and input compilerDoc. Its not really a public format, but you can look at compilerDoc::ApiDocParser for details.

Login or Signup to reply.