[haiku-doc] Re: Revert doxygen to version 1.7.6
- From: John Scipione <jscipione@xxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Sun, 23 Dec 2012 12:17:29 -0500
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.
>>> 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.
Other related posts:
