Hi list,

I want to document
packages/fcl-db/src/sqldb/interbase/ibconnection.pp

So I run this to get started:
makeskel --disable-private --emit-class-separator --update --package=fcl-sqldb
--input=/home/reinier/fpc271/packages/fcl-db/src/sqldb/interbase/ibconnection.pp --output=ibconnection.pp

What do I enter as package? fcl-sqldb? How do I find out? (And if so, can that be documented for amateurs like me?)
Apart from that, is this the right command to start?

I suppose that the output should actually be added to sqldb.xml, is that correct? Do I submit a patch or just the additional file?

Once again, thanks for the help,
Reinier

There is no rule. In this particular case, I would use fcl as a package. fcl-db may also be an option later on.

Apart from that, is this the right command to start?

You can drop the '--update', if it is the first time. and the output option should be
--output=ibconnection.xml,
not
--output=ibconnection.pp

I suppose that the output should actually be added to sqldb.xml, is that correct? Do I submit a patch or just the additional file?

It should not be added to sqldb.xml, but in its own file. Each unit should come with its associated XML file. (this is not an fpdoc restriction, but something I do, it eases managing the documentation)

Please note that I do not include documentation for a unit in the official docs unless all identifiers in the unit have been documented.

Michael.

I would even go as far as to say.... Leave Makeskel completely - it generates too much noise. Just write the documentation by hand using your favourite editor. I use Lazarus IDE or MSEide. For each editor I have created a bunch of Code Template shortcuts for use with fpdoc XML files. You end up with much cleaner XML in the end - and something that is easier to maintain. I also wouldn't bother with indentation in the XML - it's of no use to fpdoc - it rather just causes problems with some of the fpdoc output targets.

I'm not sure why you recommend leaving makeskel ?
I use it always for the initial file ? Given the proper parameters, it creates a very usable initial file ?

Michael.

I'm not sure why you recommend leaving makeskel ? I use it always for the initial file ? Given the proper parameters, it creates a very usable initial file ?

Maybe fpdoc has improved in those areas since I found the issues with makeskel generated xml files. So this might be a moot point now. From memory (this was a long time back), makeskel generates many empty tags for each element. Often documentation wasn't added in each of those empty nodes, yet the nodes exist in the xml.

Lets take the following example:

<element name="SomeName">
<short/>
<descr>Some cool description</descr>
<seealso/>
<example/>
</element>

Problem #1:
Some tags might get populated with content, and others might be left empty. fpdoc generate headers for some of those empty tags, even though they did not contain content.

Just an example (not saying this is how fpdoc works now)

Synopsis: some text here

      Declaration:  procedure MyProc(....);
    Parameters:  [blank]
     Visibility: default

Description: some long description here
See also: [blank]
Example: [blank]

Like I said, fpdoc might have been fixed now. But I do remember seeing in some of the fpdoc output writers that titles were generated like "Example" or "See Also", but then there was no content.

Problem #2:
Makeskel generates XML that are indented for human readability. This causes problems with some output writers. XML, HTML & LaTeX might ignore whitespace or CR/LF characters in the final output, but other output writers like RTF, IPF and TXT don't. Thus your might have malformed help text.

eg:
<element name="SomeName">
<short/>
<descr>This is some long description.
My second sentence.
</descr>
<example>...</example>
</element>

vs

<element name="SomeName">
<short/>
<descr>This is some long description. My second sentence.</descr> <example>...</example>
</element>

Some output writers will interpret the first example as some actual text, then CR/LF, then more text, then " " spaces (the indentation level of the xml nodes).

So instead of ending with something like:

---------------------------------
Description:
This is some long description. My second sentence.

Example:
.....
---------------------------------

...you end up with something like ....

---------------------------------
Description:
This is some long description. <-- unwanted line break My second sentence.

Example:
.....
---------------------------------

... or sometimes something like....

---------------------------------
Description:
<--
unwanted blank line
This is some long description. <-- unwanted line break My second sentence.

Example:
.....
---------------------------------

depending where the CR or LF characters were placed in the XML.

I have seen problem #2 quite often. Next time I see it again, I'll file a bug report with a screenshot. I tried fixing this problem before by simply using something like Trim(...) inside those specific output writers, but that caused all kinds of problems.

On Thu, 17 Nov 2011, Reinier Olislagers wrote: > I want to document > packages/fcl-db/src/sqldb/interbase/ibconnection.pp

<snip stuff about makeskel>

> What do I enter as package? fcl-sqldb? How do I find out? (And if so, > can that be documented for amateurs like me?) There is no rule. In this particular case, I would use fcl as a package. fcl-db may also be an option later on.

Ok, thanks. (sqldb has fcl-sqldb, that's why I guessed that name)

You can drop the '--update', if it is the first time.

Did that on purpose, so I won't overwrite my documentation when I copy/paste the command when updating the identifiers ;)

and the output option should be --output=ibconnection.xml, not --output=ibconnection.pp

Yep, typo, sorry.

It should not be added to sqldb.xml, but in its own file. Each unit should come with its associated XML file. (this is not an fpdoc restriction, but something I do, it eases managing the documentation)

Sensible. sqldb.xml is already fairly big.

Please note that I do not include documentation for a unit in the official docs unless all identifiers in the unit have been documented.

Thanks, I know, but does that include the internal (private) ones? That would seem a bit restrictive...
sqldb.xml seems to have a fair number of private identifiers without any identifiers, so I guess I answered my own question...

Thanks,
Reinier

Reinier Olislagers wrote

Thanks, I know, but does that include the internal (private) ones? That would seem a bit restrictive...

No, as far as I know that restriction only applies to Public and Published visibility.

It only generates empty tags. If you say 'update' then it generates a new file with empty tags for elements for which no tag was found.

So as far as I could see, none of the issues you quoted are with makeskel ?

Michael.

It only generates empty tags. If you say 'update' then it generates a new file with empty tags for elements for which no tag was found.

I'm not referring to the update action of makeskel, I meant the first time you run makeskel, it generates empty tags - as it was designed. But some of fpdoc's output writers did not look if those tags are empty, they simply saw the tag, and just assumed there was content, so it always went ahead and generate some output title (eg: Description, Synopsis etc). I think even some of my last fpdoc patches fixed a few of these cases. So yes, issue #1 is probably solved by now.

The second issue I mentioned happens far more often that the first issue. But yes, I guess my issues are more related to fpdoc than makeskel. So my recommendation to not use makeskel is probably more of a work-around for issue #2.