Re: [myhdl-list] docstrings forwarded to converted output

[Angel E. <ang...@gm...>]

Jan Decaluwe <jan <at> jandecaluwe.com> writes:

> 
> Angel Ezquerra wrote:
> >> On Tue, Jun 29, 2010 at 4:47 PM, Jan Decaluwe <jan <at> jandecaluwe.com>
> > wrote:I just pushed a changeset which is supposed to add support
> >> for forwarding docstrings to converted output.
> >> This provides a way to document the converted output.
> >> Ordinary Python comments are ignored, because they are
> >> not kept in the ast tree generated by the ast module.
> >> But any docstring is forwarded. Those on "official places"
> >> are put on a hopefully logical position, but "unofficial"
> >> ones are forwarded also, right on the line where they
> >> occur. By using a docstring instead of an ordinary comment,
> >> you can control which comments should be kept by the
> >> conversion, and which not.
> >> This is an experimental feature, not extensively tested.
> >> Let us know what you find.
> >> Jan
> > 
> > 
> > Jan,
> > 
> > I just gave this a try but it does not work for me. I download the latest
> > version from the mercurial repository and then I ran the rom.py example. This
> > example has some docstrings and also calls toVHDL, so I figured that it would
> > generate a rom.vhd file which should have the docstring (as a comment?).
> 
> Correct.
> 
> > However there is no trace of the docstring on the vhdl output.
> > 
> > Is there something that I should do to enable this feature? Or am I doing
> > something wrong?
> 
> Below you see what I get - the docstring as a VHDL comment as
> expected. Are you sure you are seeing the latest version
> (either after a fresh install, or by making sure that your
> PYTHONPATH sees your local repository first)?
> 

Thank you Jan. It turns out that it was an installation problem on my end. I had
updated my local mercurial repository, but I had forgotten to run "python
setup.py install"! Sorry about that!

Now it works fine. This feature is _very_ cool! :-D

One slightly weird thing that I have noticed is that while most docstrings are
converted into comments which are put before the corresonding line in the
generated code, entity docstrings seem to be placed after the entity
declaration. Is that on intentional?


Also, is there a way to add comments for ports using this method?