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

[Kenichi Asai <asai@is.ocha.ac.jp>]

[-- 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 --]