[Caml-list] OCamlDoc: @-tags handled only in the standard elements?

[Caml-list] OCamlDoc: @-tags handled only in the standard elements?

[Kenichi Asai]

I thought I could provide documents in two languages using custom tags
in OCamlDoc, but there still remains a problem.  It appears that the
custom tags (in my case, @en and @jp) are not handled in

- the very first comment,
- special comments between elements, and
- comments for type constructors, etc.

Is there any way to support custom tags in all the places including
the above?  -- Currently, it seems not, as the OCamlDoc says:

http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html

Section 15.2.1:

> (** Special comments can be placed between elements and are kept
>     by the OCamldoc tool, but are not associated to any element.
>     @-tags in these comments are ignored.*)

Section 15.2.3:

> Some elements support only a subset of all @-tags. Tags that are not
> relevant to the documented element are simply ignored. For instance,
> all tags are ignored when documenting type constructors, record
> fields, and class inheritance clauses. Similarly, a @param tag on a
> class instance variable is ignored.

Why aren't all the comments handled in the same way?  It appears to be
easier to handle all the comments in the same way.  Is there any
chance that it will become as such?

Sincerely,

-- 
Kenichi Asai

Re: [Caml-list] OCamlDoc: @-tags handled only in the standard elements?

[Gabriel Scherer]

[-- Attachment #1: Type: text/plain, Size: 2109 bytes --]

My understanding is that these parts of the documentation describe the
behavior of the generators provided by ocamldoc. If you implement a custom
generator to handle those custom tags (Section 15.3), you should be able to
override this behavior with whatever pleases you. If the current
implementation does not allow that, you should file a feature request and
indeed it seems reasonable to extend it suitably.

Do you have the sources of your current experiment available somewhere for
testing and reproduction?

On Tue, Dec 9, 2014 at 7:42 AM, Kenichi Asai <asai@is.ocha.ac.jp> wrote:

> I thought I could provide documents in two languages using custom tags
> in OCamlDoc, but there still remains a problem.  It appears that the
> custom tags (in my case, @en and @jp) are not handled in
>
> - the very first comment,
> - special comments between elements, and
> - comments for type constructors, etc.
>
> Is there any way to support custom tags in all the places including
> the above?  -- Currently, it seems not, as the OCamlDoc says:
>
> http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html
>
> Section 15.2.1:
>
> > (** Special comments can be placed between elements and are kept
> >     by the OCamldoc tool, but are not associated to any element.
> >     @-tags in these comments are ignored.*)
>
> Section 15.2.3:
>
> > Some elements support only a subset of all @-tags. Tags that are not
> > relevant to the documented element are simply ignored. For instance,
> > all tags are ignored when documenting type constructors, record
> > fields, and class inheritance clauses. Similarly, a @param tag on a
> > class instance variable is ignored.
>
> Why aren't all the comments handled in the same way?  It appears to be
> easier to handle all the comments in the same way.  Is there any
> chance that it will become as such?
>
> Sincerely,
>
> --
> Kenichi Asai
>
> --
> Caml-list mailing list.  Subscription management and archives:
> https://sympa.inria.fr/sympa/arc/caml-list
> Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
> Bug reports: http://caml.inria.fr/bin/caml-bugs
>

[-- Attachment #2: Type: text/html, Size: 2956 bytes --]

Re: [Caml-list] OCamlDoc: @-tags handled only in the standard elements?

[Kenichi Asai]

[-- Attachment #1: Type: text/plain, Size: 3127 bytes --]

> Do you have the sources of your current experiment available somewhere for
> testing and reproduction?

Thank you for the e-mail.  I created a very small example attached.
When you run "make" in the test directory, html documents are created
in the html-* directories.  I want the following:

- I want the first text "module header in *" to appear in index.html.
  (If I remove "@en", the text appears there.)

- I want the two "Session header" texts to appear in Test.html.

- I want the the texts for "A" and "B" to appear in Test.html.

In a nutshell, I want all the @en texts to appear and @ja texts to
disappear when I pass "-lang en" (and likewise for "-lang ja").

Sincerely,

-- 
Kenichi Asai


On Tue, Dec 09, 2014 at 08:38:45AM +0100,
 Gabriel Scherer wrote:

> My understanding is that these parts of the documentation describe the behavior
> of the generators provided by ocamldoc. If you implement a custom generator to
> handle those custom tags (Section 15.3), you should be able to override this
> behavior with whatever pleases you. If the current implementation does not
> allow that, you should file a feature request and indeed it seems reasonable to
> extend it suitably.
> 
> Do you have the sources of your current experiment available somewhere for
> testing and reproduction?
> 
> On Tue, Dec 9, 2014 at 7:42 AM, Kenichi Asai <asai@is.ocha.ac.jp> wrote:
> 
>     I thought I could provide documents in two languages using custom tags
>     in OCamlDoc, but there still remains a problem.  It appears that the
>     custom tags (in my case, @en and @jp) are not handled in
> 
>     - the very first comment,
>     - special comments between elements, and
>     - comments for type constructors, etc.
> 
>     Is there any way to support custom tags in all the places including
>     the above?  -- Currently, it seems not, as the OCamlDoc says:
> 
>     http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html
> 
>     Section 15.2.1:
> 
>     > (** Special comments can be placed between elements and are kept
>     >     by the OCamldoc tool, but are not associated to any element.
>     >     @-tags in these comments are ignored.*)
> 
>     Section 15.2.3:
> 
>     > Some elements support only a subset of all @-tags. Tags that are not
>     > relevant to the documented element are simply ignored. For instance,
>     > all tags are ignored when documenting type constructors, record
>     > fields, and class inheritance clauses. Similarly, a @param tag on a
>     > class instance variable is ignored.
> 
>     Why aren't all the comments handled in the same way?  It appears to be
>     easier to handle all the comments in the same way.  Is there any
>     chance that it will become as such?
> 
>     Sincerely,
>    
>     --
>     Kenichi Asai
> 
>     --
>     Caml-list mailing list.  Subscription management and archives:
>     https://sympa.inria.fr/sympa/arc/caml-list
>     Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
>     Bug reports: http://caml.inria.fr/bin/caml-bugs

[-- Attachment #2: test.tar.gz --]
[-- Type: application/x-tar-gz, Size: 1066 bytes --]