[haiku-doc] Re: Revert doxygen to version 1.7.6
- From: John Scipione <jscipione@xxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Sun, 23 Dec 2012 14:48:28 -0500
On Sun, Dec 23, 2012 at 2:29 PM, Niels Sascha Reedijk
<niels.reedijk@xxxxxxxxx> wrote:
> 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?
Doesn't appear to have worked no, I guess we need to wait for a cron
job to update the git repository on the server?
Other related posts:
