[fpc-pascal] State of FPC docs.rant

[Joseph Montanez]

I just spent 2 hours on FPDoc's trying to get how to use it. Automatic
documentation was dead easy but the whole XML integration part was a
nightmare, so I gave up reading the docs on how to use the doc.
Instead I figure "Hey there must be examples of this right?" ... *digs
through source* ... 5 mins later figured it out.

Spent another hour making a pretty example, found out there was no CSS
file generated, and made my own:
http://www.gorilla3d.com/fpdoc/animal/tanimal.talk.html

Here is everything I used to generate it:
http://www.gorilla3d.com/fpdoc/tanimal.zip

Now to think I am going dealing with XML isn't so bad, but the SVN
interaction is painful, Git is no different. The reason I like the
Wiki so much is that if I click "edit" I see the wiki source, change
it and it compiles right there and then. I don't have to download the
source code from SVN, recompile each time, submit a patch, etc.

Ideally if I could edit the very page
http://www.gorilla3d.com/fpdoc/animal/tanimal.create.html and only see
the XML data for that segment, I would be in bliss. Problem is it wont
work for building new docs. FPDoc requires a pascal unit (source code)
to try to generate documentation, the part I *hate* about automated
documentation. Pascal is one of the few language that you can look in
the source code and really READ, so the automated part is of no help
other then linking inheritance together and what not.

In the end if we start raiding the Wiki, it would allow anyone to
contribute documentation which should be looked at, edited and put
into the true documentation of FPC. A lot of administration work no
one wants to do.



On Mon, Apr 26, 2010 at 5:00 PM, John <jszcmpr at netspace.net.au> wrote:
> On 26/04/2010 11:52 PM, Graeme Geldenhuys wrote:
> ...
>>
>> John het geskryf:
>>>
>>>  On the other hand, Joseph has a point -
>>> I have worked out most bits of  FPC over the course of a few years, but
>>>
>> Granted that the bulk of FPC's documentation is simply Class or API
>> documentation. A more "new developer" friendly help is needed. If memory
>> serves me well, Michael van Canneyt did say his wants to (or is busy)
>> writing such "newbie" documentation. Included in that will be a section on
>> Object Oriented Programming.
>>
> I think you missed my point.  I don't need 'new developer' documentation for
> OOP.  What I can't understand is how the documentation system itself works,
> ie, how to go about using it to contribute documentation.  (Or even how to
> install it locally, for that matter - So I use what is on the web or trawl
> through the source code (at least we have that option ) )
>>>
>>> another site.  My suggestion would be to just put it on the Lazarus
>>> wiki,
>>>
>> The Lazarus wiki is now a combined FPC and Lazarus wiki.
>>
> So it is!  I hadn't noticed that.  The FPC wiki used only to have links to
> the pdfs, IIRC.
>>
>> Regards,
>>   - Graeme -
>>
> cheers,
> John
>
> _______________________________________________
> fpc-pascal maillist  -  fpc-pascal at lists.freepascal.org
> http://lists.freepascal.org/mailman/listinfo/fpc-pascal
>



-- 
Joseph Montanez
Web Developer
Gorilla3D
Design, Develop, Deploy