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.
How are the apidoc files accessed/viewed?
Should this option be also generating the html files in the doc directory of the fantom install?
How does one go from fan doc syntax in their code into the html files?
go4Wed 27 Feb 2019
Do you mean how to generate documents?
Generate all doc:
fan compilerDoc -all
By pod name:
fan compilerDoc util
SlimerDudeWed 27 Feb 2019
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:
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.
brianThu 14 Mar 2019
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.
jhughes Wed 27 Feb 2019
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.
go4 Wed 27 Feb 2019
Do you mean how to generate documents?
Generate all doc:
By pod name:
SlimerDude Wed 27 Feb 2019
.apidocfiles are machine readable versions of Fantom type documentation. They let you distribute API documentation without the source code.As
go4noted, HTML documentation may be generated bycompilerDocand yes, this is a rather undocumented feature..apidocfiles allow other software to read and display Fantom documentation, examples of which are:jhughes Wed 27 Feb 2019
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?
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 2019
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.