[aspectc-user] Improvements for reference documentation around AspectC++ 2.0?

[Olaf Spinczyk]

Hello Markus,

thanks for pointing out these deficiencies in the language reference!
See my comments below ...

Am 27.02.2016 um 19:45 schrieb Markus Elfring:
>> The new release, AspectC++ 2.0, is now available
> I find this information interesting.
>
>
> Now I have looked into the corresponding language reference documentation again.
> http://aspectc.org/doc/ac-languageref.pdf
>
> 1. How do you think about to publish it also in a HTML format structure?

Good point. We should definitely look into this. For many year our web
pages were managed with a CMS that made it difficult to have
auto-generated documentation pages. However, we longer have this
restriction.

>
> 2. Should such a document contain a version identification?

The version number on the cover page refers to the documented ac++
version, while the date reflects the version of the document. We
normally don't have more than one update per day.

>
> 3. I have noticed that a link to the AspectC++ Programming Guide does not work
>    at the moment. Where should it be usually stored on the server?

Correct, this was a broken link. I made an update and removed the whole
sentence. Referring to a manual that hasn't been written yet is pointless.

>
> 4. The "List of Examples" contains an entry "advice placement, ??".
>    Which page number is missing here?

The label, which was referred there does not exist. I have removed
"advice placement" from the list, because I don't know which example
might be meant here.

>
> 5. Would you like to use a monospace font for the XML file display
>    under the chapter "Project Repository File For Example"?

Fixed.

>
> 6. How do you think about to start each chapter on a new page?

This a matter of the latex style we use. I'm not sure if that would
really look nicer. For instance, the chapter "1 About" is very short.

>
> 7. How does the promising description for the functionality "get(pointcut)"
>    in the section "4.7 Variables" fit to the question "Will 'set' and 'get'
>    be supported in the near future?" at an other place?
>    http://aspectc.org/FAQ.php#faq12

The FAQ was outdated. I modified the question and the answer so that it
make more sense.

>
> 8. I am particularly interested in the handling of various functions.
> * Would it be a bit more appropriate to refer to the identifier "MemPool::alloc"
>   in the section "Example: function matching"?

In contrast to checking whether dealloc is called with a NULL-pointer
argument we could also check alloc is with a size of 0. However, the
difference doesn't matter much, right? Or did I miss the point here?

>
> * Can an advice become context-dependent?

What do you mean by "context-dependent"? Something like the "if"
pointcut function in AspectJ? You have a certain context dependency with
'that' and 'target', which dynamically check the object's type.

>
> * Do any attributes or special annotations matter?

At the moment AspectC++ is ignoring attributes, which is for some
platforms a bit dangerous, because (gnu) attributes can affect parameter
types.

>
> * Is it possible to adjust a specific source code change by taking the function
>   call hierarchy into account?

Not yet. The problem is that ac++ sees a single translation unit only,
which contains only a fraction of the call graph. However, we are
working on that already.

>
> 9. How are advice libraries evolving?

There is only one useful library at the moment, which is JPTL
(Joint-Point Template Library). It can be found under tests/JPTL/JPTL.h
and helps to work with the compile-time information provided by the
static JoinPoint-API.

>
> Regards,
> Markus
>

Thanks for your help,

Olaf