[haiku-doc] Re: Revert doxygen to version 1.7.6
- From: Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Sun, 23 Dec 2012 20:29:46 +0100
Hi,
On Sun, Dec 23, 2012 at 6:17 PM, John Scipione <jscipione@xxxxxxxxx> wrote:
> On Sun, Dec 23, 2012 at 5:25 AM, Niels Sascha Reedijk
> <niels.reedijk@xxxxxxxxx> wrote:
>> Hi,
>>
>> On Sat, Dec 22, 2012 at 11:15 PM, John Scipione <jscipione@xxxxxxxxx> wrote:
>>> On Sat, Dec 22, 2012 at 4:35 PM, Niels Sascha Reedijk
>>> <niels.reedijk@xxxxxxxxx> wrote:
>>>>> Given that the documentation is broken on 1.8.1 installed on the
>>>>> server right now can we revert to 1.7.6 for the time being? We can
>>>>> update the code to look good and then update to the 1.8.x branch again
>>>>> later on.
>>>>
>>>> Yes, or not. I still want to see whether switching to the wiki
>>>> approach will work. I am sort of stuck on finding a roadmap right now.
>>>> I would also like to think about how we approach things like
>>>> organizing functions and creating navigation.
>>>
>>> I also think that is a good approach, at least I'm not in love with
>>> Doxygen. Problem is that Doxygen seems to be the best program out
>>> there for source code documentation. The wiki would be a good
>>> secondary solution though. We'd lose all the code checking that
>>> doxygen does, but the barrier to entry of fixing the docs would be
>>> lowered. If we could get a few more people involved in documentation
>>> writing it would be a net win.
>>
>> Actually, the checking with the header field would not be lost. The
>> wiki pages can be cross-checked with the Doxygen output and then it is
>> possible to find out which changes are there.
>
> I don't understand this, Doxygen doesn't produce very parseable
> warning output so it would be tough to use this to do checking on the
> wiki page. Are you referring to the generated documentation output?
> Even then I fail to see how you could cross-check the the doxygen
> output. Perhaps if you were to read the XML you could check that way.
Re-parse the wiki page. Compare to the parsed XML. The current
skeletons on dev.haiku-os.org are also generated from the XML. That
should make it possible to see the differences between the members of
the header file and the actual documentation.
>>>> Will we use header files as package containers (which is not really a
>>>> C++ convention, nor a Haiku one), or will we just use a liberal way of
>>>> organizing it? Like putting all the support kit functions on one page?
>>>
>>> I would organize classes by kit that seems to be the most reasonable
>>> way to organize them.
>>
>> So what do we do with functions, defines, enums, typedefs and what
>> else that are there? Organize by topic (like the BeBook does it) or
>> organize by header file (like Doxygen).
>
> I guess organize by header would be the way to go. I'd have to think
> about it some more.
>
>>>> Anyway, I will try to downgrade the server to 1.7.6.
>>>
>>> Okay, that will be helpful in the interim, at least the
>>> api.haiku-os.org page will look decent again.
>>
>> It is back at 1.7.5.1 and the documentation has already been regenerated.
>
> Output looks good again on 1.7.5.1, but, it doesn't seem to be pulling
> in my latest documentation changes. Missing BFile, BCursor, etc.
Yes I see, it looks like the script is not updating the git
repository. I updated the script now. Did it work?
Regards,
N>
Other related posts:
