[sword-devel] OT: project issues (was: Re: single-user vs. multi-user installations, modules and packaging)

[DM Smith]

On Sep 24, 2007, at 7:10 AM, Jonathan Morgan wrote:

> On 9/24/07, Eeli Kaikkonen <eekaikko at mail.student.oulu.fi> wrote:
>> On Mon, 24 Sep 2007, Jonathan Morgan wrote:
>>>> How do I export the content of the modules so I can store it in my
>>>> own format?"
>>>
>>> Might this not need better documentation of the Sword project tools,
>>> rather than the API?
>>
>> I think he meant that people would be more willing to write software
>> using our library. That would remove the need of conversion.
>
> That makes sense, though I don't think that will overcome the "I want
> to use language X, for some value of X unserved by SwigSword".

Eeli was right.

Actually, I think it *should* swerve them.

The effort to write a good Bible search and lookup library is not  
trivial. Over the few years that I have participated here, I have  
seen many people get started and few get very far. We need to help  
people understand that we can get further together than separately.

But on another note, I work on JSword, so I know the itch to port.  
I've been working at it for 3.5 years now, fairly steadily, and there  
is still so much more to be done. I'm not about to stop now, but if I  
had put that energy into Sword C++ it would have been well served.


>
>>> I think that there are a few separate issues here:
>>> 1. Documentation of the API.  This should consist of  
>>> documentation of
>>> what the classes are for, what the individual methods do, etc.
>>> 2. Documentation of the Sword tools.  This should consist of
>>> documentation of input file formats, purpose, command line  
>>> arguments,
>>> etc.
>>> 3. Documentation for the various GUIs.  This should consist  
>>> largely of
>>> user manuals and similar things.
>>
>> Exactly, but the library is for developers and frontends for end  
>> users.
>> Therefore their documentation projects are not related.
>>
>>> I think that in all these areas there is some work done.  I think  
>>> what
>>> Eeli and Karl were looking at was (1), while DM may be looking  
>>> more at
>>> (2) and (3) (correct me if I'm wrong).
>>
>> I was actually thinking of 1 and 2 though it might not be clear from
>> what I wrote.

And I was thinking of 1 and 2 also. But perhaps not 1 in the way you  
were. I think you were thinking more of a Java style of documentation  
where every Public method and Public class is documented as to its  
purpose, parameters,  products (return values) and problems (aka  
exceptions) (I just had to make it all  P's :) . I'm using Public  
here as opposed to public to mean the interface which is part of the  
published API and not one that is artificially public because of an  
internal library need. That is, what one should know about as opposed  
to what one can call.

Such documentation is invaluable and it should be done, but I was  
thinking more of explained Snippets of code. It is more important to  
know how a method works in concert with everything else and how it  
helps to achieve a real goal.

As to 3, that belongs in the hands of each frontend development team.  
I know that GnomeSword and BibleDesktop have current, comprehensive  
and even complete documentation (That makes 3 C's :)


>
>>> with different audiences, I think that there is a real danger of
>>> trying to lump them together and either ending up with one source  
>>> for
>>> documentation which doesn't really meet any needs, or with some  
>>> needs
>>> not being met at all.  For example, (1) would be definitely targeted
>>> at developers, (2) is probably directed at module developers (though
>>> they should have some knowledge of command line tools, etc.), and  
>>> (3)
>>> should be directed at end users.
>>
>> Number 3 is out of our scope as I mentioned. I don't see any  
>> reason why
>> things should be "lumped together". Having a centralized page for
>> developer documentation is not lumping together. I don't  
>> understand what
>> you mean by "one source". See how Qt documentation is consistent  
>> in form
>> and style, yet very useful for their audiences.
>
> That was a reaction to DM's statement:
> "With regard to documentation, we
> all have the ability to provide it and make it available via the
> wiki. That's what the wiki's home page states it is for."
>
> I don't think that the Wiki is appropriate for the API documentation I
> was talking about, so the Wiki was the "one source" I was targeting.
>
>>> 1. API documentation: This should probably be kept with the  
>>> source at
>>> this stage.  I am aware that there are some arguments for separating
>>> this from the source for documentation of major software libraries
>>> like Mono (such as internationalisation), but I think at the moment
>>> the library is struggling to have adequate documentation in one
>>> language.  From this documentation can be generated, and there is a
>>> higher chance of it being kept in sync with the code.
>>
>> This is right and I don't see a reason why we should ever remove  
>> the doc
>> from the code files. Few widespread sofware libraries have 18n'ed  
>> docs
>> (or am I wrong? Haven't researched lately...). Keeping the  
>> translations
>> up to date would be almost impossible for us.
>
> Which is why I said it.

I agree with this statement, but I don't think it goes far enough.  
API documentation is needed for two fundamental purposes:
1) to understand a particular method so that the class to which it  
belongs can be fixed or improved (i.e. for library writers)
2) to understand a particular method so that the class can be used in  
another context (i.e. for library users)

The problem I have had with C/C++ is the best way to achieve this.  
 From the library writers' perspective, it should be in the code  
file. From the library users' perspective it should be in the header  
file. If it is in the header file it directly impacts compile time  
(compilers are getting better with header caching and incremental  
compilation, but it is a hit on a big library) My preference is to  
have it only in one of these two spots, preferably the code file, and  
be able to pull it from there to create library users' documentation.

The other part of this problem for me is that there is no  
documentation standard for C/C++. I see quite a variety of  
documentation within Sword code and headers.

Doxygen only goes so far.

That said, there is doxygen generated API documentation available in  
SVN, http://www.crosswire.org/svn/sword-apidoc/trunk. Given the  
revision number, I don't think this is maintained as part of each  
release of Sword.

That said, I think the wiki should point to this kind of  
documentation and that it should be kept current with each release as  
a release activity.

But the wiki should be the home to Snippets and short but full  
working examples.

>
>>> 2. Tool documentation: Basic documentation of what individual  
>>> tools do
>>> should probably be with the source.  More detailed user level things
>>> like "What tools should I use to create a module?", "How do each of
>>> the tools fit into the big picture?", "How do I create an OSIS
>>> module?", etc. probably belong on the Wiki, as has been done to a
>>> reasonable extent.
>>
>> That's true. Using wiki is practical for these kind of things.

I'll be writing it for osis2mod very soon. Nice thing about it, it is  
the big picture for a Sword OSIS Bible module. It is the only needed  
tool.